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Chapter 1 


Introduction 


The word “render” isn’t unique to the vocabulary of computer graphics. We can talk about a 
“watercolor rendering,” a “musical rendering” or a “poetic rendering.” In each of these, there 
is a transformation from one domain to another: from the landscape before the painter to color 
on paper, from musical notation to sound, from the associations in a poet’s mind to a book of 
poetry. 
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Figure 1.1: Czar’s Waiting Room, Main Railway Station, Helsinki, Elel Saarinen, 1910, watercolor. 


But the type of rendering that may come closest to what we mean when we talk about rendering 
in computer graphics is in architecture. Geometric blueprints and technical specifications of 
building materials are transformed in the architectural rendering into a picture of the building 
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as it will appear when construction is complete. In addition to the designs of the building’s 
geometry and its visual characteristics, the artist chooses a point of view to depict the scene in 
perspective. This is a transformation of a description of imagined space into a picture of that 
space. 


In a watercolor by architect Eliel Saarinen (Figure 1.1), the effect of light on marble is 
demonstrated in a way that would be lost in even a careful reading of blueprints and descriptions of 
materials. A mere brushstroke of a particular color in a particular place paradoxically transforms 
the dull matte appearance of watercolor into the sheen of polished stone. 


Rendering in mental ray is a similar act of transformation, a computerized process that results in a 
digital image, a mosaic of numbers displayed as color. Here the intuitive skill of the artist has been 
replaced by a rendering program that requires an unambiguous description as input. And like 
Saarinen’s watercolor, the evocation of materials and space is performed by color alone. 


In this book, we'll be rendering pictures from descriptions in three dimensions. These 
descriptions specify the scene to be rendered: the shape of objects, how they look, the nature 
of the environment, the light that shines in the space, and the position and orientation of an 
imaginary camera that takes a virtual photograph of it all. Frequently, the measure of the success 
of three-dimensional renderings will be how much they do in fact look like photographs. 


Figure 1.2: Draughtsman Drawing a Recumbent Woman, Albrecht Diirer, 1525, woodcut. 


But the lure of duplicating the appearance of the world is hardly new, nor is the use of mechanical 
devices to achieve that similarity, as with Durer’s draughtsman and his transfer of a grid laid 
over the world to a grid on paper (Figure 1.2). Though much of computer graphics research has 
been devoted to “photo-realism”—the realistic duplication of a photograph—nothing limits a 
rendering program to the physics of light. Along the way we’ll also see how we can use color 
and line in a manner that follows our own sense of how a picture should look, of an imagined 
visual reality (Figure 1.3). 
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Figure 1.3: Composition VIII, Wassily Kandinsky, 1923, oil. 


1.1. Avisual hierarchy: color, light, shape, space, image 


The design of software is often called its architecture. This is a natural metaphor, coming from 
the sense that the software is a structure of various compartments, with movement between them, 
built on a foundation of assumptions about who will inhabit it. 


The mental ray rendering software is itself a pretty tall building. But it also provides for users of 
the software to make their own additions to its structures. These additions are called “shaders,” 
and are executed throughout the whole of the rendering process. The first two volumes in 
the mental ray documentation series, Rendering with mental ray and Programming mental ray, 
describe the role shaders play in mental ray rendering, how you can write your own shaders, and 
how you add your shaders to the rendering process. 


Documentation of software is often a description of its architecture. However, this may not be 
the most useful way to guide the novice through the software’s hallways. The most important 
aspect of a building may be that it is a skyscraper, but we still enter through a door that is not 
much taller than we are. 


For programmers new to computer graphics or artists new to programming, the blueprints of a 
building like mental ray can be daunting. This book reorders the way that shader programming 1s 
usually presented based on the idea of a visual hierarchy, that everything we see in an image is not 
of equal importance to our visual experience. Painters have long understood this; representational 
painting styles may differ in what is included and what is omitted by the painter during the process 
of representing the world in paint. 


Individual experience, however, will argue for one ordering of the hierarchy over another. Do 
you find the overall color of an object more or less important than its shape? The psychology of 
perception has a lot to say about this, too. Some factors are hard-wired into our consciousness, 
like the eye-brain mechanism that emphasizes edges (and which results in the uneven coloring 
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known as Mach banding). Other factors are cultural or based on the unique experiences of the 
individual. 


For the purposes of this book, however, we’ll replace scientific accuracy (and cultural sensitivity) 
with this model: you open your eyes and colors take form, molded by the light that falls across 
and defines the shape of the surfaces, diffusing into the space, forming an image that you can 
understand. With this, we can divide up our visual experience—and the order in which we learn 
about mental ray shaders—into five broad categories: 


Color The simplest shader will just specify a single color for an object. We’ll start there, and 
then define color based on the position of the object or the orientation of its surface, adding 
color extracted from other images or suggested by edges and silhouettes. 


Light The simulation of light on objects is a key component when creating images that look like 
photographs. Simulated lights in the scene are also specified by shaders, and we’ll write 
shaders that define lights, exploring how they affect the look of an object with other shaders 
that simulate shadows, reflection, refraction, and the visually realistic effects we can obtain 
when we take the entire environment into account. 


Shape Shaders can modify the apparent shape of a surface or actually change the geometry of the 
object being rendered. We'll write shaders to make these modifications to a pre-existing 
object. We'll also write shaders that create geometric objects from scratch, beginning with 
a single square and ending with the simulation of hair, cacti, water and fire. 


Space Our geometric definition of an object is typically a description of the surface of the object. 
But what about the space between the surfaces? We’ll write shaders that describe what 
happens to light in between objects and within them as we simulate the effect of fog, dust, 
and smoke. 


Image So far, we’ve been thinking of the objects and lights as they exist in the scene to be 
rendered, but we can also create shaders that are concerned with the rendered image itself. 
We’ll use shaders to modify the simulated camera as it constructs an image from the scene, 
creating wide-angle lenses and the blurred effects of depth of field. At the end of the process 
begun by the camera, mental ray creates a digital image, and we’ll write shaders that can 
modify that image at the final output stage. 


Before we start to write shaders of our own, we need to consider how the shaders fit into the 
rendering process, so the book begins with a description of the structure of the mental ray scene 
and the shaders used within it: 


Structure A shader can be used in many different ways in our description of the scene to 
be rendered, and our intended use of the shader will influence its design. The structure 
of shader code is also based on a few recurring software patterns that provide a useful 
background as we write shaders of our own. 


This concern for structure affects the entire book. Separating an image into visually intuitive 
components is a useful first step on a path to creating more complex effects. Much of the book 
describes the development of individual shaders, but these shaders can also be combined in shader 
graphs, in which individual shaders contribute to the final rendered effect in a network of input 
and output. Modularity is a powerfully flexible concept in software design, and shaders can be 
connected in a modular way to bring that same flexibility to rendering. 


1.2. What you need to know to write mental ray shaders 5 


1.2. What you need to know to write mental ray shaders 


How to program in C. Shaders in mental ray are written in the C programming language, 
supported by a library of mental ray functions. Shaders can optionally be written in 
C++ to take advantage of existing libraries or if you prefer the syntactic extension to C 
that C++ provides. This book does not teach you how to program in C, but my extensive 
use of utility functions in the implementation of shaders should help clarify what the C 
code is doing. For instructional books on C and C++ programming, I recommend Patrick 
Henry Winston’s On to C [Winston 94a] and On to C++ [Winston 94b]. Compilation of 
shaders on a variety of platforms is described in Programming mental ray and inthe on-line Prog 186, 3.1. Dynamic 
version of that book that is part of the mental ray software distribution. Rapenp on enadars 


The structure of the scene file. Because shaders can be used in a variety of ways in the scene, 
Part 1: Structure describes the structure of the scene file and its possible variations for you 
to explore as you develop your own shaders. Writing shaders is as much an experimental 
art as it is one of programming. You can copy the scene files provided by the book’s website 
(see Section 1.4) and modify them to better understand how mental ray defines a visual 
world through a file of text. 


How mental ray renders. Shaders in mental ray can be invoked throughout the rendering 
process, from the time each ray initially leaves the camera until the final set of pixels 
are ready to be written to disk. To be able to write a shader that uses the advanced features 
of mental ray requires you to understand how that shader functions during rendering. 
However, this book begins with simple examples that let us ignore, for the moment, the 
more complex mechanisms available in the rendering process. By working through the 
various types of shaders presented during the course of this book, you will also develop a 
better understanding of how mental ray renders a scene. 


The current state of rendering research. It’s not strictly necessary that you keep up with the 
current state of the research in three-dimensional rendering, but mental ray provides an 
excellent test bed—through shader programming—for a variety of research areas. You can 
certainly get inspiration and practical advice from other books on rendering. In particular, 
Physically Based Rendering: From Theory to Implementation, by Matt Pharr and Greg 
Humphrey [Pharr 04], provides extensive theoretical explanations for many of the issues 
we will briefly encounter during our tour of shader types. Their book implements Donald 
Knuth’s strategy of literate programming, in which the program and its documentation 
coexist. In some ways, this book is the inverse: a set of individual rendering functions to 
be tied together and seen as a whole through the argument of the text, promoting, I hope, 
some programmatic literacy in the process. And though we'll be more concerned here with 
the efficiency of our understanding of the code, the efficiency of its actual execution should 
never be far from our minds. Books like Realistic Ray Tracing, by Peter Shirley and R. 
Keith Morely [Shirley 03], provide a discussion of computational efficiency as well as the 
theoretical explanations that can complement our investigation into mental ray’s approach 
to various rendering problems. Geometry for Computer Graphics: Formulae, Examples 
and Proofs by John Vince [Vince 05] is an encyclopedic collection of the mathematical 
formulae that are useful in solving these problems. 


Rend 11, 1.2.4. Cameras 
Prog 41, 1.31. Contours 


Prog 18, 1.12. Texture 
Mapping and Texture 
Files 


Rend 178, 7.1. Photon 
Mapping vs. Final 
Gathering 


Prog 307, 3.26. Functions for 
Shaders 
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1.3 Howto read this book 


Throughout the book, marginal notes provide pointers to further discussion of the current topic 
in the third edition of the first two volumes of mental ray documentation. For Rendering with 
mental ray [Driemeyer 05a], the page number is preceded by “Rend” and followed by the title of 
the containing section, as in this pointer to the subsection titled “Cameras.” For Programming 
mental ray [Driemeyer O5b], the prefix is “Prog”, for example, in this pointer to the section on 
contour shading in the “Functionality” chapter of that book. Essential reference information is 
sometimes provided in this way; the “wide variety of image file formats” mentioned on page 83 
is fully documented in Programming mental ray in the section to which the marginal note refers, 
“Texture Mapping and Texture Files.” The marginal notes also point to explanatory material that 
more fully describes the concepts involved in the current shader under discussion. For example, 
Section 7.1 in Rendering with mental ray, “Photon Mapping vs. Final Gathering” describes the 
different applications of those two techniques that will be useful in understanding Chapter 16, 
“Light from other surfaces.” This book, then, can be used as an introduction to mental ray as 
new topics are introduced by following the corresponding references to Volumes I and I. On 
the other hand, experienced shader writers will also find the book useful as a reference; I will 
repeat marginal reference in order to make each section somewhat self-sufficient. A separate 
index on page 619 contains all the marginal references in this book to Rendering with mental ray 
and Programming mental ray, listed by section, so that you can easily determine if a topic in the 
first two volumes is discussed in this one. 


Programming mental ray is distributed with the mental ray software as a set of HTML pages. 
The marginal references in this book include the section or subsection name; you can search in 
the table of contents to find the hyperlink to that page in the HTML manual. The index in the 
on-line version of Programming mental ray also provides hyperlinks to the documentation. For 
the functions provided by mental ray for use in shaders, these hyperlinked index entries simplify 
finding the documentation for a new function encountered in the example shader code in this 
book. Under the topic “auxiliary functions,” the index of this book also includes references to 
the functions we develop as useful components in the course of writing shaders, beginning in 
Chapter 7, “Color from position.” 


All the images in the book rendered from the example scenes can be found in Appendix A 
beginning on page 457. Each image is labeled with the page in which it appears in the body of the 
text, and can be useful as a visual index when you want to look up a shader based on the imagery 
it creates. Appendix B on page 475 is a complete source code listing of all shaders presented in 
the book, including the number of the page in which the shader is first described in the text. The 
source code of all auxiliary functions used in a shader are also included after it in the order of their 
execution. These two appendices can be used to review the imagery and source code presented 
in the book and as an encyclopedia of techniques. 


The mental ray scene description plays a large role in the way that shaders are used in rendering, 
and the first part, Structure, describes this relationship. In the following parts of the book, each 
chapter develops the ideas necessary to write a single type of shader. More experienced mental 
ray users may already be familiar with the structural issues developed in the first part of the book. 
If you feel that you already understand how shaders are used in the scene file (for example, the 
difference between a shader graph and a Phenomenon), you may skip directly to the chapters 
that describe the types of shaders in which you are interested. 


On the other hand, Part 1: Structure describes the scene file and the structure of shaders in an 
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overview that should be useful for everyone. If we understand the larger patterns at work in 
a complex software system, we will better be able to extend that system in a manner that is 
consistent with its original design. 


1.4 Web-based resources 


The source code and the scene files used throughout the book can be downloaded from the book’s 
website, http: //www.writingshaders.com. Errors discovered by helpful readers can be sent 
to the e-mail address included there, and a page of errata will record their findings. And since 
a book of the scope that is attempted here can’t actually be finished, but, in Marcel Duchamp’s 
phrase, become at some point “definitively incomplete,” the website will also contain additional 
material that will clarify omissions or describe new techniques suggested by the strategy I’ve 
outlined in these pages. 
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Chapter 2 


The structure of the scene 


How do we describe the scene to be rendered in a manner that mental ray can understand? 
Notice that even in asking this question we’re already engaged in a metaphor—mental ray 
doesn’t understand anything; there is input and the program produces output. But to simplify 
our creation of the input, it would be better if it related to our own intentions behind the picture, 
not to the pattern of bits that will be read (another metaphor) by mental ray. 


2.1. The scene in mental ray 


Usually when we think about three-dimensional computer graphics, our primary metaphor is 
photography: we point a camera at a space containing illuminated objects. In this book, we’ll 
describe the world to be rendered with similar concepts, but in a text file in the .mi scene 
description language. In a representation of the scene in this language, called a scene file, we'll 
describe the camera, objects, and lights. We also need to describe how the scene should look when 
rendered, and that specification is the responsibility of shaders in mental ray. The name “shader” 
is deceptive, however; though surface colors are calculated by shaders, they can do much more 
than that, including the creation of geometric objects (as we'll see in Chapter 19). 


What kinds of things do we need to describe to mental ray? We'll look first at some components 
of a scene file, and then see how they fit together to create a description that mental ray can 
render. 


2.2 A block of statements with a name 


The component parts of a scene (like objects and cameras) are called the elements of the scene file. 
Many of the elements of the scene file have a similar structure in which the element is defined in 
a block of text. For example, a camera is defined like this: 


Rend 5, 1.2. Scenes and 
Animations 


Prog 59, 2. Scene Description 
Language 


Rend 33, 2.1. A Simple Scene 
Rend 11, 1.3. Shaders 
Prog 191, 3.3. Shader Type 


Overview 


Prog 83, 2.7. Scene Entities 


Rend 39, 3. Cameras 


Prog 105, 2.7.2. Cameras 


Rend 417, 19. The Options 
Block 


Rend 6, 1.2.1. Geometric 
Objects 


Prog 124, 2.7.8. Objects 
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camera "camera" 
output "Tapa" "EAE" "Dicture. tit" 
focal 35 


aperture we DS 

aspect BI Ce 

resolution 200 150 
end camera 


Figure 2.1: Camera definition 


The camera block begins with camera, a reserved word in the .mi scene description language. 
Between the camera and end camera lines are statements that describe the camera. You don’t 
need to include all the statements that define an element. If a statement is missing, a default value 
for that statement is used instead. This is convenient when there are many possible statements 
for an element, but you only want to specify values for a few of them. 


For example, the way that a scene will be rendered, its rendering options that control, is controlled 
by statements in the options element. There are over ninety options statements, but you only 
need to include a statement when you want to override its default value. So an options block 
may be as simple as this: 


options "options" 
object space 


COMCTASt «4d. ah add 
end options 


Figure 2.2: The options block 


The name for the options block follows the options reserved word. I called this options block 
options, an obvious choice for such a simple scene. But the reserved word for the options block 
is also options—how do we tell which words are reserved and which words are names we’ve 
given to scene elements? Quotation marks make a difference: "options" is the way I specify 
my name for the options block I am defining, but options is a word that starts this block in the 
mi language. We also know which is which because of the order of the two words: first comes a 
predefined word in the mi language (options) and then the name I am giving this particular set 
of options in my scene file. 


For both cameras and options, you can see that the form of the elements is similar, with a set of 
statements surrounded by the type of block in the beginning with its name, and the word end at 


the end. 


element-type "element-name" 
statements 
end element-type 


Figure 2.3: Structure of an element in the scene file 


2.3 A block that includes another block 


To add a geometric object to the scene, you must first define it. Here’s a simple definition of a 
unit square centered around the origin in the z=0 plane: 
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object "Square" 
visible 


group 


Vv 
Bp. O02 
end group 

end object 


Figure 2.4: Definition of an object called “square” 


Typically, you will not be defining a geometric model in a text editor, but will use geometric 
definitions constructed in some modeling application. In this example, however, we can see that 
some blocks can contain other blocks, like the group block that defines the vertices of the object’s 
single polygon. The group block is indented more than the other parts of the object block 
to clarify its nested structure. Indentation in the scene file is not necessary, however, and all 
redundant whitespace characters (extra spaces, tabs, newlines, etc.) are ignored when the scene 
file is read by mental ray. 


2.4 A block containing a shader 


In mental ray, a material includes everything specific to an object that defines how it will look 
when rendered. In the scene file, the material is represented as a list of shaders of different types. 
We'll be putting many of the shaders we write into materials that we attach to objects, and as we 
develop more complex techniques, we’ll include a variety of shader types in the material. (As 
we'll see, shaders are also used to define the behavior of lights and cameras.) 


Here’s a simple example of a material that contains just one shader, called one_color, the first 
shader we'll write in Part 2: 


material "yellow" 


"one color" ( "color" 11 0 
end material 


Figure 2.5: A simple material named “yellow” containing shader “one_color” 


You can see that the material block follows the same overall structure as the camera and the square, 
and that its name is yellow. However, the parentheses are something new. They surround shader 
parameters, a list of names for input data for the shader followed by their respective values. In 
this case, the single parameter color has the value 1 1 0. Ina more complex shader, there may be 
many of these parameters, each separated by a comma. 


For example, if shader one_color had two parameters, color and tint, the name/value pairs 
would each be separated by a comma: 


Prog 134, 2.7.9. Polygonal 
Geometry 


Rend 9, 1.2.2. Materials 


Prog 61, 2.1.1. Parameter 
Types 


Prog 739, B. Scene File 
Grammar 


Rend 371, 14.1. Instances 


Prog 170, 2.7.15. Instances 
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material "yellow" 
"one color” { 
"olor, 1 

rei” 


) 


end material 


Figure 2.6: A material containing a shader with two parameters 


Here the parentheses and shader parameters are split across several lines, which is allowed since 
extra whitespace characters are not significant. We could have defined the previous yellow 
material like this: 


material “yellow” “one color" ("color" 1 1 0) end material 


Figure 2.7: A material element formatted on a single line of text 


It’s still correct, just harder to read. Indenting lines in the scene file by different amounts makes 
the relationship of its parts clearer to the eye. 


2.5 A block that refers to another block 


When the square was specified by the object block, mental ray treated those eleven lines of text 
as a definition of four connected points in space to create a shape. But how did it know to do 
that? And where did the shape go once it did? As mental ray reads the scene file, it interprets, or 
parses, its various blocks and performs different actions based on the nature of the block. Any 
object block is added by mental ray to its ongoing definition of the scene to be rendered, the 
scene database. 


Once an object has been added to the scene database, however, it needs to be placed somewhere 
in the scene to be rendered and associated with a material to specify how it should look. This 
bundle of information—the object, its material, and its placement—are combined to create an 
instance, the database element that is used during rendering. 


The placement of the object is defined by a transformation matrix, sixteen numbers that encode 
how the object as originally defined will be scaled, rotated and translated. The transformation 
matrix in the instance is optional, however, and without it the instance is rendered using the 
original position, orientation and scaling of the object itself. 


An object is defined only once but can be instanced many times. You can think of instancing 
an object as the process of manufacturing the shape to be rendered from the original object 
definition. For example, the following instance element, made from the previously defined 
square object, defines an instance called yellow-square. 
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instance "yellow-square" "square" 
material "yellow" 
transform 


1 0 


0 dl 
0 60 
-2 -1 
end instance 


Figure 2.8: An instance of object “square” called “yellow-square” 


The material for an instance can be defined with a material statement in the instance block. Prog 114, 2.7.4. Materials 
Like the square object, the material in this instance block, yellow, was previously defined. This 

is one of the few restrictions on the order of the elements in a scene file: an element must be 

defined before it is referenced by another element. 


To render a scene using a particular camera, we need to create an instance of it in the same way 
that we made an instance of an object. The previously defined camera, called camera, is instanced 
using the name main-camera in another instance block, adding a transformation matrix to 
position the camera in the space. 


instance "main-camera" "camera" 
transform 
1 0O 
0 dl 


0 
@) 
oo @ a2 
0 O -9 
end instance 


Figure 2.9: An instance of “camera” called “camera-instance” 


When we create an instance of an object or a camera, we need to refer to a previous block, but 
also give the instance a new name. 


instance "new-instance-name" "existing-element-name" 
statements 
end instance 


Figure 2.10: Creation of an instance from a camera or an object 


There are two quoted strings the beginning of the block: the name of the new block we are  Rend35, 2.2. Anatomy of a 
creating and then the name of the previously defined block which will be instanced to create it. — 

Remember, however, that the textual layout of the .mi scene file is arbitrary; the camera block 

could also look like Figure 2.11. 


Rend 373, 14.2. Instance 
Groups 


Prog 173, 2.7.16. Instance 
Groups 


Rend 36, 2.2. Anatomy of a 
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Prog 79, 2.6.2. Shader 
Compilation and Linking 


Prog 74, 2.6. Commands 
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instance "main-camera" 
"camera" 
transform 
a. 


0 
0 
0 


end instance 


Figure 2.11: A camera instance with an alternate text format 


If you are writing an application that generates .mi scene files directly, you are free to format the 
scene file text in the manner that best expresses the structure implied by the application. 


2.6 Grouping the elements in the scene 


We’ve only defined a single instance, but there can be any number in the scene file. Instances 
can be organized into hierarchies of any complexity using instance groups. Before we begin to 
render the scene, we will need to specify the top-level group that will contain all the instances to 
be rendered. In our simple scene, we’ve only instanced a square, so the top-level instance group 
will only contain the square and camera instances. Defining the instgroup block follows the 
common pattern: a reserved word (instgroup), the name for the block, additional information 
appropriate for the type of block, and the final end statement. 


instgroup "root" 


"main-camera" "yellow-square" 
end instgroup 


Figure 2.12: The root instance group for scene containing the elements to be used in rendering 


To construct an object hierarchy, an instgroup block can contain other instance groups as well 
as other objects. In modeling applications, a hierarchy is often a natural way to represent large 
structures, and this organization in the application can be represented in the scene database with 
the instgroup element. 


2.7. Scene file commands 


All the previous examples showed the various elements that can be contained in the scene file. 
The scene file can also contain commands that do not define elements but tell mental ray to 
perform an action at the point in the scene file where the command occurs. 


For example, to use a shader in a scene file we need to do two things: 
1. Load the compiled shader into memory when rendering begins; and 


2. Declare the data types of the shader and its parameters so that its use later in the scene file 
can be correctly parsed. 


In the scene file, shader loading and declaration are usually done using the link and $include 
commands, respectively. For example, to use the one_color shader in our simple scene, these 
commands are included at the beginning of the file: 
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link "one _color.so" 


sinclude "one color.mi" 


Figure 2.13: The link and $include statements required to use a shader 


In this case, we’ve put the shader declaration in a separate file for convenience, and used the 
$include command to insert it into the scene file at that position. Here’s an example of a shader 
declaration: 


declare shader 
color “one color" ({ color "celer" 9 
version 1 

end declare 


Figure 2.14: The declaration of a shader 


Finally, we use the scene file command render at the end of the scene description to start the Prog77, 2.6. Commands 
actual rendering process once we’ve got all the pieces we need: the root instance group, a camera 
instance, and a set of rendering options: 


render "root" "main-camera" "options" 
Figure 2.15: The render command 


2.8 Putting the parts together 


The individual components of the scene are connected when one part refers to another part by 

its name, and so we can create a diagram of these relationships. Because you can’t refer to a part Rend 38, 2.2. Anatomy of a 
by its name until it’s been defined, the diagram shows the parts of the scene file from left to right, iii 

with the arrows pointing to previously defined parts. 


Scene file 
root instance group 


camera instance 
camera camera 


object instance 


ahieet render 
material 


Figure 2.16: The hierarchical structure of the scene 
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2.9 Acomplete scene file 


Rend 32, 2.1. A Simple Scene A scene file made from the elements and commands we’ve seen so far could look like this: 


verbose on 
link “one color .so" 
Sinclude "one _color.mi" 


options "options" 
object space 
Contrast «<1 4.1 sd 
end options 


camera "Camera" 
output 'roba" “Cit” "picture,.tit" 
focal 35 
aperture 2205 
aspect LsSoos 
resolution 200 150 
end camera 


instance "main-camera" "camera" 
transform 
1 OO O 
Oo 1 0 
0 O 1 
0 O -9 
end instance 


material "yellow" 
"one color" { "eelor" 1:1..0 
end material 


object "Square" 
visible 
group 


Vv Vv 
Dp 0-1 
end group 
end object 


instance "yellow-square" "square" 
material "yellow" 
transform 
1.49 
o 12 
0 O 
-2 -1 
end instance 


instgroup "root" 
"main-camera" "yellow-square" 


end instgroup 


render "root" "main-camera" "options" 


Figure 2.17: A complete scene file 
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The filename of the scene file is an argument to the command line version of mental ray, called 
mental ray standalone. If the scene file in Figure 2.17 is named square_scene.mi, then the 
following command executed in a command shell would render it: 


ray square_scene.mi 


This is the picture that is rendered from the scene file: 


Figure 2.18: Rendering of scene file square_scene.mi 


Though this is a trivially simple scene, scene files of far greater complexity will still share many 
of its structural elements. The components of all scene files share this same structure with its 
grammatical overtones. You can think of the various block types (like cameras and objects) as 
the nouns. The statements in the block modify the blocks, like adjectives. Shaders perform much 
of the actions taken by the renderer, like verbs, with parameters that serve as adverbs to modify 
them. Finally, there are commands, like render that also act like verbs on a larger scale. 


2.10 Thescene file and 3D applications 


In this book, we’ll be using scene files as the input to the command-line version of mental 
ray. These scene files will use the shaders we develop in the course of the book. For any 3D 
application that includes mental ray as one of its rendering options, the same shaders can also be 
made available as menu choices in the application. 


Each application will provide its own mechanism for adding your custom shaders to its graphical 
interface. However, the same mental ray rendering process is used in the application or in the 
command line version. Your custom shaders can also be designed to supplement the capabilities 
of the existing set of shaders in the application. 


Prog 709, A.1. mental ray 


Prog 739, B. Scene File 
Grammar 


Prog 709, A. Command Line 
Options 


Prog 571, 5. Integration of 
mental ray 


Prog 571, 5. Integration of 
mental ray 
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standalone 
mental ray 


application 


scene file application 


mental ray 


mental ray application custom 
base shaders shaders shaders 


Figure 2.19: Shaders, 3D applications, standalone mental ray, and the mental ray core 


Applications also typically provide the ability to generate, or export, a mental ray scene file. This 
file can then serve as input to the standalone version of mental ray. You should construct a simple 
scene in the application, export the mental ray scene file, and then examine it in a text editor. It 
will be far more complex than our simple example of the yellow square, but the same structures 
will be used no matter how large the scene. 


As you write shaders, you can use a 3D application to generate a scene file and then replace 
its shaders with the new ones you are developing. Once you’ve finished the development 
process using this method, you can add your shaders to the application’s graphical interface. 
Artists can then choose your shaders from the interface as if they were part of its standard 
configuration. 


As a programmer, however, you are not limited to exporting scene files from 3D applications. 
Based on the example of the scene files we'll develop throughout the book, you can also write your 
own scene file generator that can serve as input to the standalone version of mental ray. 


ce standalone 
your custom program .mi file 
mental ray 


Figure 2.20: The .mi scene file as the input to mental ray from your program 


The block structure of the scene file that we’ve been investigating in this chapter also simplifies 
translating the scene data generated by other applications. The only requirement of the source 
application is that it can export data into a format that you can understand. 


— ; ae standalone 
any application your translation program mental ray 


Figure 2.21: The .mi scene file as the output of your translation program 


scene data 
in some format 


Chapter 3 


The structure of a shader 


As we'll see in the course of this book, shaders in mental ray are used throughout the rendering 
process and for very different purposes. For most shader types, there is a standard structure for Prog 191, 3.3. Shader Type 


the inputs and outputs that you can rely on when you are writing a new shader. To begin to make eee 

sense of that structure, we’ll start with a really simple idea for a shader and expand what it can 

do until we arrive at one of the basic structures for shaders in mental ray. Rend 271, 11. Shaders and 
Phenomena 


3.1 Defining a color with a shader 


Shaders produce data used by mental ray in the rendering process. The simplest possible shader 
would just generate a single color. As we saw in the last chapter, the material in the instance 
defines the surface color. We could use shaders there that produced a standard set of colors. 


Figure 3.1: A shader that always produces the same color 


A shader that only produces a single color wouldn’t be very useful, however—for each new color 
we'd need to write a new shader. It would be better if we could specify an arbitrary color (for 
example, as a list of numbers in the scene file) and have the shader provide that color to the 


material. 


Figure 3.2: A shader that provides the color supplied as an input 


If the shader also modifies the input color before providing it to the material, then we can think 
of developing a set of shaders that define standard ways of processing colors to produce a new 
ones. 


Prog 61, 2.1.1. Parameter 
Types 
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Shader Material 


"input color > color modification output color 


Figure 3.3: Modifying an input color to produce a new color 


But this shader is as limited in its own way as the shader that only defined a color was—the 
process that manipulates the color can’t be modified. 


3.2 Providing input to a shader 


So far we’ve only been thinking of simple kinds of shaders that supply colors to a material. To 
continue to generalize our idea of a shader, we can consider a shader that takes arbitrary input 
data and performs some computation with it to generate its output. In turn, the shader should 
also be able to provide as output arbitrary kinds of data that are useful in the material, and not 
simply color. 


Shader Material 


Figure 3.4: Modifying an arbitrary input value 


But you may want to give your shader more than one piece of information to be used in its 
calculations. For example, there could be three different items of input data that we want to 
provide to the shader—two different colors that should be combined based on some third input, 


a fractional value. 
Shader Material 


Figure 3.5: Supplying multiple inputs to a shader 


We don’t want to limit the situations in which we can use shaders during the rendering process, 
but different contexts will require different numbers and kinds of inputs. From a programming 
standpoint, we don’t want a special case for each type of shader—one type of shader for a single 
input, another type for two inputs, yet another for three, and so on. Since we don’t want to 
limit the kind of input we’ll give to any shader, we’ll consolidate the input data into a single 
structure. 
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Shader Material 


parameters computation result 


Figure 3.6: Using the parameter input as a container for arbitrary amounts of data 


We'll call the consolidated set of the shader’s input data its parameters. These parameters can be Prog 226, 3.5. Shader 


arbitrarily complicated, but will look like a single input as far as the shader is concerned. 


3.3. Telling the shader about its context 


What about other information that the shader needs and can’t be supplied as an input in the scene 
file, but consists of the rendering context in which the shader is being used? For example, what if 
we want to know the orientation of the surface in space where the shader 1s calculating a color? 
The shader needs information from mental ray, not just from the inputs that you’ve provided to 
It. 


Shader Material 


parameters 


computation result 


Figure 3.7: Adding the current rendering state as an input to the shader 


We'll call the information from mental ray the rendering state and add it as a separate input to 
the shader. The shader can examine the state and use the information it contains as further input 
to its computation. 


3.4 Accumulating the effect of a series of shaders 


What if we want to use more than one shader at a time? For example, we might realize that 
we have two different shaders that both do some of the work we want done by a single shader. 
Rather than writing a new shader that just combines two others, it would be useful if we could 
supply the output of one shader to another shader for further modification. 


Parameter Declarations 


Prog 198, 3.4. State Variables 
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Material 


Figure 3.8: Providing the result of the previous shader as an input 


We'll call the output of a shader its result. By connecting the result of one shader to another 
Rend 277, 11.3. Shader Lists. | shader as an input, we can make a chain of shaders, or a shader list. 
Prog 68, 2.3. Shader Lists 


3.5 Combining the previous and current results 
We’re now close to the basic structure of shaders in mental ray. But not all shaders will need to 
use the previous result. Since the same kind of data will be produced by the previous shader of 


this type, we'll combine the input and output slots into a slot in the diagram. The dotted lines 
indicate that not all shaders will be using the previous shader’s result, but that it might be used in 


the current shader. 


= 
Figure 3.9 is the model for most of the mental ray shader types and their implementation as 


functions in C. With this idea of the structure for shader inputs and outputs, we can now take a 
look at the various roles a shader can play in the scene. 


Shader 


result 
i] 


Vv 


Figure 3.9: The standard shader input/output model 


Chapter 4 


Shaders in the scene 


In the previous two chapters, we saw the overall structure of the scene file and the structure of 
an individual shader. In this chapter, we’ll take a look at how they fit together—how shaders 
in the scene can be named, how their parameters and results can be connected, and how a set 
of shaders can be bundled together into larger structures that simplify the creation of complex 
shader effects. 


4.1 Describing parameters: shader declarations 


Shaders use and produce different types of data, such as numbers, vectors and arrays. One of 
the fundamental types is color. A color consists of a number of color components, usually red, 
green and blue. It may also contain a fourth channel, alpha, which can be used to represent other 
attributes, like transparency. Shaders define colors in C with the mental ray data type miColor. 
When a shader calculates a color, it is specifying a value for a variable of type miColor. 


For example, let’s say that we want to write a shader that multiplies one color by another. We'll 
define the first color to be the base color, and the second color to be a scale factor. 


base-color x scale-factor-color = result-color 


Figure 4.1: Multiplying colors 


These two colors to be multiplied will be the parameters of the shader. What does it mean to 
multiply two colors together? We simply multiply the respective components of the two colors 
to create the components of the resulting color. 


base _ color 
(parameter) 


result 
(output) 


scaled_color 


(shader) 


scale factor 
(parameter) 
Figure 4.2: A shader to multiply two colors 


If our variables are pointers of type miColor, then the shader code can reference the components 
of the color with the “->” pointer syntax in C: 


Prog 33, 1.27. Color 
Calculations 
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result->r = base color->r * scale factor->r; 


result->g base color->q * scale factor-sq; 
result->b = base color->b * scale factor->b; 


Figure 4.3: Multiplying color components in C 


Rend 272, 11.1. Declarations | For such a shader to be used in a scene, we need to specify the names of the shader’s parameters 
Prog 60, 2.1. Shader and their data types in the scene file. This is called the shader declaration. The declaration enables 
idaciniaeld mental ray to associate the parameter values in the scene file with the parameter argument in the 

C shader function. 


A shader is declared in the scene file in a block like many of the other scene’s elements: 
declare shader 


color "scaled_color" ( 
color "base _ color", 


color "scale factor" 


) 


end declare 


Figure 4.4: A shader declaration 


Prog 61, 2.1.1. Parameter Each of the parameters has a name and a data type. The data type of the shader is the data 
ia type of the shader’s result. These type/name pairs are the elements of the shader parameter list. 
Each pair is separated from other pairs in the list by a comma, and the list is surrounded by 

parentheses. 


declare shader 


: 
[color]|"base_color’ 
) 


end declare 


Result type Shader name 
Parameter type 


Parameter type 


Parameter name 
Parameter name 


Figure 4.5: Parameter names and data types in a shader declaration 


Rend 275, 11.2. Definitions | When the shader is used in the scene file, the parameters are given specific values appropriate to 
Prog 66, 2.2. Shader their datatype. This is called a shader definition. Like the shader declarations, the parameter/value 
Demeitions pairs in a definition are separated by commas and surrounded by parentheses. 


"scaled color" { 
"base color" 


"Seale Tactor” 


Figure 4.6: A shader definition 


The names of the parameters in a shader definition correspond to the names in the shader 
declaration. The types of parameter values must correspond to the types in the declaration. 
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Shader name 


fracaied corer] 


Parameter value 
Parameter value 


Parameter name 
Parameter name 


Figure 4.7: Parameter names and values in a shader definition 


Color parameter values are specified by listing the red, green, blue and alpha components 
separated by spaces. If alpha is missing, it defaults to 1.0. Using the parameter values for 
the scaled_color shader in the previous figure, the scaled_color shader will calculate a result 
color of 0.9 0.9 0.0. 


4.2 Missing parameter values: defining defaults 


You do not need to specify all the parameters in a shader definition. By default, the parameter 
values supplied to the shader will be zero, or a value like zero appropriate for the data type. 
For example, the default value for colors is opaque black (zero for red, green, blue, and one for 


alpha). 


However, it is often useful to provide a default value other than zero for a parameter. To specify 
such a value, you follow the parameter name with the word default and the default value. This 
is now part of the declaration, so the comma that separates the parameters follows the default 
value. 


declare shader 
color “scaled color" { 
color "base color" défault 111, 


color "scale factor" default 1 1 1 


) 


end declare 


Figure 4.8: A shader declaration with default values 


Any missing parameter in a shader definition uses the default value for that parameter. And 
because the value of a parameter is determined by its association with the parameter’s name, the 
order in which the parameters are listed is not significant. 


All the parameter types that can define their values explicitly in the scene file (for example, the 
scalar components of colors and vectors) can also specify a default value. For parameter values 
that refer to elements in the scene (like a list of light tags), defaults cannot be specified. The 
shader function itself will need to examine the parameter value and substitute a default value if 
the parameter has not been defined. By default this value is zero, but in the case where zero is 
a valid value for the parameter, you can specify an invalid value that serves as a signal that the 
shader should substitute the actual default. (See shader average_radiance_options on page 229 
for the use of -1 as a signal value.) 


The scene file examples so far have been formatted to emphasize the structure of the shader. 
However, as we saw in Chapter 2, the white space in the scene file is ignored. (We’ll make use 
of this insignificance of white space characters in later shader declarations, putting the closing 
parenthesis on the last line of the parameter list to reduce the length of the diagrams.) The format 


Prog 61, 2.1.1. Parameter 
Types 
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of numbers is also not important, so “1.0” is the same as “1”. This means that we could also 
create a shader definition from the scaled_color shader with a default argument like this: 


"scaled_ color" ("base color" 1 1 0) 


Figure 4.9: A definition of scaled_color using a default value for scale_factor 


Because of default values for parameters, you may not be able to know all the possible parameters 
of a shader by looking at a shader definition in a scene file. However, the shader declaration 
provides a complete description of the shader’s parameters and any defaults that have been 


defined. 


Rend525,C. BaseShaders_ For example, the standard mental ray distribution includes a set of base shaders that provide 
examples for most of the various shader types and can be used as the base set of shaders 
in constructing more complex combinations of shaders we’ll see later in this chapter. The 
declarations of all the base shaders is provided by a file named base .mi contained in the software 
distribution. Here’s the declaration in base.mi for the base shader that implements ambient 

Rend 548, C.6. Illumination — occlusion, a technique we'll develop in Section 16.6: 


declare shader 
color "mib_amb_occlusion" ( 
integer "samples" default 
color "bright" default 
color "dark" default 
scalar "spread" default 
scalar "max_distance" default 
boolean "reflective" default 
integer "output_mode" default 


boolean "occlusion_in alpha" default 
# Version 2 parameters 
scalar "falloff" default 


integer "id inclexcl" default 
integer "id nonself" default 
) 
version 2 
apply texture, light 
end declare 


Figure 4.10: Declaration of the ambient occlusion shader in the standard mental ray shader library 


After the shader declaration, the version number of the shader is defined by the version reserved 
Rend 284, 11.5.2. Shaderand word, one of the shader options that can be added to the shader declaration. By referencing the 
Phenomenon Options version number defined in the C code of the shader to which the declaration refers, inconsistencies 
‘ oe between the declaration and the C function can be determined during rendering and reported as 
an error by mental ray. The version option isn’t necessary, but it’s a good idea to include it in 

all your shader declarations. 


The declaration of mib_amb_occlusion also includes the apply option. It isn’t used by mental ray, 
but can be referenced by applications to organize shaders by result type in their menu interface. 
(The apply option will be quite important when we create lens shaders in Chapter 24 because of 
the assumptions lens shaders make about the rendering state that are different than most other 


shaders.) 
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Notice the use of the # character to include a comment to this declaration. The # character and 
the rest of the line are ignored by mental ray when it parses the scene file. Comments are useful 
for adding descriptive information to scene files. 


4.3 Defining the material: anonymous and named shaders 


As we briefly explored in Chapter 2, a material is a collection of shaders and their parameter Prog 114, 2.7.4. Materials 
values that define how an object will be rendered. In the material, the shader’s abstract properties 
are given actual values, like 1 1 0 for yellow where a color is required. The shader and its set 
of actual parameter values is called a shader definition. Separately from its use in a material, 
however, a shader definition can be named and added to the database as an element. As a named 
shader in the scene database, we are then able to refer to it ina material. By contrast, if the shader 
and its parameters are used directly in the material, it is called an anonymous shader. Without a 
name, the anonymous shader cannot be referenced elsewhere in the scene. Though the parameter 
values of an anonymous shader can easily be read from the material itself, we'll see later in this 
chapter how naming enables the construction of complex shader combinations in a variety of 
useful ways. 


4.3.1 Anonymous shaders 


For an anonymous shader, the shader name and its parameter values—the shader definition—are 
included within the material itself. 


Scene file 


Material material "yellow" 
"scaled color" [{ 


"base color" 
Anonymous shader = 


‘arate Tactor™ 


) 


end material 


Figure 4.11: Anonymous shader in a material 


At its simplest, the material for an object describes its color through the result value of the single 

shader it contains. But many different types of shaders can be specified by a material to specify a 

variety of effects: how it defines shadows, the object’s environment, even geometric manipulation 

of its surface. These optional shaders are preceded by a shader type identifier that defines the Prog 13, 1.7. Materials 
category of the shaders that follow it. 


For example, the shadow shaders we’ll develop in Chapter 13 are specified in the material with 
the shadow identifier in the material: 


Prog 237, 3.8. Material 
Shaders 


Prog 67, 2.2. Shader 
Definitions 


Rend 277, 11.3. Shader Lists 
Prog 68, 2.3. Shader Lists 
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material "transparent_25" 


"transparent" ( 
"color? =. "tile: shader", 
"“Eraneparency” .25 .25 .25 


Material shader 


Identifier for optional shader 


"shadow color" ( 
"color". = "tile, shader", 
"transparency" .25 .25 .25 


Shadow shader (optional) 


end material 


Figure 4.12: Material with a shadow statement and shadow shader 


For the remaining examples in this chapter, we’ll be using one or more shaders responsible for 
the color defined by the material. These shaders are called material shaders. The other shaders 
we'll add in later chapters are known by the shader type identifier we specify in the material, for 
example, shadow shaders, environment shaders, and displacement shaders. 


4.3.2. Named shaders 


To allow materials and other shaders to refer to the same shader definition, we can create a named 
shader by including a shader element in the scene file that contains the shader definition. Once 
we’ve named a shader definition, we can refer to it by that name. 


Scene file 


shader "yellow_shader" 
"scaled color" ( 
Named shader tee "base color" 
"scale factor" 


) 


Material 


material "yellow" 


end material 


Figure 4.13: Named shader in a material referring to a previous shader definition 


Notice the use of the equals sign (=) in the material. This indicates that what follows is not a 
shader definition itself (an anonymous shader), but is the name of a previous shader definition. 
The dotted line in Figure 4.13 indicates such a reference to a named shader. To use a named 
shader, it must already have been defined; you cannot reference a shader named later in the scene 


file. 


4.4 Chaining shaders of the same result type: shader lists 


In Chapter 3, we developed the idea of a shader receiving the result of a “previous shader.” A 
previous shader exists when there is a shader list, specified in the material as a series of shader 
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definitions of the same type. The shader functions are called in the order of the list. After the 
first shader in the list, successive shaders have access to the result of the previous shader to use in 
their calculations. 


4.4.1 Using the result of the previous shader 


Let’s say that we have a shader that will add a color to the result of the previous shader. 
Like multiplying two colors, the result of adding two colors is a color created by adding their 
components. Because we’re modifying the result color in the shader, we will use the C “+=” 
operator: 


result->r += color to _add->r; 


result->g += color _to_add->g; 
result->b += color to _add->b; 


Figure 4.14: Adding color components in C to the previous shader’s result 


We'll call this shader "add_color". 


declare shader 
color "add_color" ( 
color ,"color Fo. ada" 
) 


end declare 


Figure 4.15: Declaration of shader add_color 


So far we’ve been ignoring the alpha component of our colors. Let’s define a shader with which 
we can set the alpha component to a given value. In C, we will only need to set the alpha field of 
the result color: 


result->a = new alpha value; 


Figure 4.16: Setting a new alpha value in C 


The new alpha value isn’t a color; it’s a single floating-point value, which will be declared as a Progé61, 2.1.1. Parameter 
“scalar” (the mental ray floating point type) in our shader declaration: aE 


declare shader 
color "set_alpha" ( 


scalar "new alpha" 


) 


end declare 


Figure 4.17: Declaration of shader set_alpha 


Both add_color and set_alpha take the result. value into account. Shader add_color adds a 
color to the current value of result, while shader set_alpha modifies the alpha, but doesn’t 
change the value of the other components of result. 


Prog 198, 3.4. State Variables 


Rend 85, 4.4. Bump Mapping 


Rend 544, C.6. Illumination 


Rend 135, 5.1. Point, Spot, 
and Infinite Lights 
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Now we can use add_color and set_alpha in a shader list: 


Scene file 


Material 


Anonymous shader material "color correct" 
"scaled color" ( 


"base color" 


"scale factor” .9 .9 . 
Anonymous shader 
( "color to add" 0 0 .2 ) 


"add color" 


"set_alpha" ( "new_alpha" 1 ) 


Anonymous shader end material 


Figure 4.18: A list of anonymous shaders in a material 


The resulting color will be 0.9 0.9 0.2 1.0. This is, of course, a trivial example—you don’t 
need a shader to multiply 1.0 by 0.9—but you can see how simple shaders can be used in sequence 
to produce more complex results. 


4.4.2 Modifying the rendering state in a shader list 


The rendering state is passed as an argument to all shaders. A shader in a list can modify certain 
parts of the state to affect shaders later in the list. For example, in a technique called bump 
mapping, we can change the apparent shape of the surface when it’s lit by changing the rendering 
state first. (As we’ll see in Chapter 18, this is implemented by changing the vector that represents 
surface orientation, the normal vector.) We can even use several bump-mapping shaders in a 
list to make successive modifications to the appearance of the surface when it’s rendered. 


If we’re going to change the vector that describes the shape of the surface, we'll need to use 
a shader that will show such a change by changing the surface color accordingly. The result 
of the constant color shaders we’ve been using in our examples so far won’t be modified by 
bump mapping. Instead, we’ll use the Phong illumination model, implemented in the mental ray 
base shader library as mib_illum_phong, since it is influenced by the light direction for its color 
calculations and will therefore show the result of bump mapping. 


We'll talk more about lights in Chapter 11 and the Phong model in Chapter 12, but for now, 
we'll say we have defined a light named light~-1 earlier in the scene file. Since a light is also an 
object to be positioned in the scene, we need to create an instance of it so that it can be used in 
rendering. The structure of the instance command for a light is the same as for objects. We'll call 
this instance light_instance. 


4.4 Chaining shaders of the same result type: shader lists 


ligne Ylightr” 
"point light” { 
"ligee coler™ 114 


) 
origin 10 10 20 
end light 


instance "light instance" 
ny ight " 
end instance 


Figure 4.19: Use of standard shader mib_point_light to create light instance sidelight 


We'll define a material that uses an anonymous mib_illum_phong shader with sidelight as the 


single light in its ight list. If we render a square with this material, we can see the slight change Prog 227, 3.5. Shader 


in gray value across the surface because of the light. 


material "waves-1" 
"mib_illum_phong" 

"diffuse" 

"Specular" 


"exponent" 50, 
"lights" ["light instance"] 


end material 


Figure 4.20: Rendering using mib_illum_phong only 


To modify the surface using bump mapping we’ll define a shader called bump_ripple that modifies 
the rendering state’s normal vector based on a sinusoidal function calculated from a position on 
the surface. (We'll write this shader in Chapter 18 beginning on page 263. Page 532, included 
in the caption of Figure 18.12, presents the complete source code of that shader. References 
to the complete shader source code are similarly marked throughout the book in other shader 


figures.) 


declare shader 
color "bump ripple" ( 
vector "center" default 


scalar "frequency" default 

scalar "amplitude" default 

scalar "nearby" default 
end declare 


Figure 4.21: Shader declaration of bump_ripple (p.532) 


Because the result of the shaders in a shader list is cumulative, we can add bump_ripple to the 
material before mib_illum_phong. The normal vector in the state is changed by bump_ripple 


Parameter Declarations 


Rend 85, 4.4. Bump Mapping 
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in a sinusoidal pattern and is apparent in the rendered image because of the color’s dependence 


Rend 52, 4.1. Color and upon the light position. 
Illumination 


material "waves-2" 


"bump ripple" ( 
"oenter™ .1 .5 @, 
"frequency" 25, 
"amplitude" .35 


"mib_illum_phong" 
"diffuse" 
"Specular" 
"exponent" 35, 
"lights" ["light instance"] 


end material 


Figure 4.22: Rendering with modification of surface normal by bump_ripple 


We can change the position of the center of the wave pattern by changing the value of the 
"center" parameter. 


material "waves-3" 

"bump ripple" ( 
'cenrcer”™: .9 ,5°G, 
"Frequency" 25, 
"amplitude" .35 


"mib_illum_phong" 
"diffuse" 
"specular" 
"exponent" 35, 
"lights" ["light instance"] 


end material 


Rig 


Figure 4.23: Shader bump_ripple with a different value for the center parameter 


Because the bump_ripple shader modifies the normal vector in the state, putting another 
bump_ripple shader in the list modifies the normal vector twice, creating an interference pattern 
from the two uses of the bump_ripple shader. 


4.4 Chaining shaders of the same result type: 


shader lists 35 


material "waves-4" 


"bump ripple" ( 
"center" ~1 
"frequency" 
"amplitude" 


ce D, 


"bump ripple" ( 
"center" .9 
"frequency" 
"amplitude" 


"mib illum_phong" 
"diffuse" .6 
"Specular" .4 


"exponent" 35, 
"lights" ["laght instance"] 


end material 


Figure 4.24: Using a bump mapping shader twice with different parameters 


By using a list, we can use the same shader with different arguments to create complex 


combinations from simple components. 


4.4.3 Named and anonymous shaders in the shader list 


Shaders in a list can be either anonymous or named. For example, we can redefine the material 
in Figure 4.24 to use three named shaders. The equals sign (=) is used as before to point from the 
name of the shader in the shader list to the definition occurring earlier in the scene file. 


Prog 68, 2.3. Shader Lists 


Prog 67, 2.2. Shader 
Definitions 
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Named shader = |€=--- : 
Named shader = |€""": 
Named shader |<: 


Material 


me - 


Scene file 


shader "shiny" 
"mib_illum_phong" 
Uditfuge™ ...6 
"Specular" .4 .4 
"exponent" 35, 
‘lagnte" - ["iight anetaence™ | 


shader "right_wave" 

"bump ripple" ( 
"SPencer +o. 0, 
"Frequency" 25, 
"amplitude" .35 


shader "left _wave" 

"bump ripple" ( 
*cencer”™ ,1 .o G, 
"Frequency" 25, 
"amplitude" .35 


material "waves with_shaders" 


- [Mete_wave"] 
- [Reight_wave" 
- [reniny*] 


end material 


Figure 4.25: A list of named shaders in a material 


In a shader list, you can mix named and anonymous shaders. They are equivalent as far as the 
definition of the material is concerned, so you can define shaders and materials in a manner that 
simplifies the definition of the scene. 


4.5 Connecting shaders in a network: shader graphs 


Scene Scene file 


Named shader << 


Material 


shader "shiny" 


"diffuse" 
"specular" 


"lights" 


37 


"mib illum_phong" 


.4 
"exponent" 35, 
["laght instance" | 


material "waves mixed" 


"bump ripple" ( 
"center" .1 
"frequency" 
"amplitude" 


Anonymous shader 
) 


"bump ripple" ( 
"center" .9 
"frequency" 
"amplitude" 


end material 
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Figure 4.26: A shader list in a material containing both anonymous and named shaders 


4.5 Connecting shaders in a network: shader graphs 


In a shader list, the result of one shader is passed to another shader as the initial value of that 
second shader’s result. We can also provide the result of one shader as the value of one of the 


input parameters of another shader. Because you can think of shader parameters as the inputs to 
a shader and the shader’s result as its output, by connecting shader inputs and outputs we can 


form a network, or a shader graph. 


Shader #1 


parameters 


Shader #3 


parameters 


Shader #2 


parameters 


Coo 6 


result 


result 


Rend 278, 11.4. Shader 
Graphs 


Prog 68, 2.4. Shader Graphs 


Figure 4.27: Shaders represented as connected nodes in a network 


In Figure 4.27, the result values of shaders #1 and #2 provide the values used for the parameters 
of shader #3. The parameters for shaders #1 and #2 could in turn have come from the result of 
other shaders. The result of shader #3 could also be used as a parameter value for another shader. 


In this way, you can construct complex connections between shaders. 
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As an example of a shader graph, we'll connect three shaders together. The first shader, 
front_bright, will calculate a color based on the orientation of the surface of the object. If 
the surface is facing the camera, it is white. If it is facing away from the camera, it will be black. 
The degree to which the surfaces the camera between these two extremes will be represented by 
shades of gray. The parameter to the shader will be multiplied with the color calculated from the 
orientation to produce the result. (We’ll define this shader on page 58.) 


declare shader 
color "front bright" { 


color "tint" default 111 ) 
end declare 


Figure 4.28: Shader declaration of front_bright (p.476) 


We’ll use this shader in a material and render a scene consisting of cylinders of uneven height to 
produce the image in Figure 4.29. 
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material "front" 
"front braghtk” . { 


Meine” 1.08 1.08 1.05 
) 


end material 


Figure 4.29: Using the front_bright shader in a material 


For a second shader in our graph, we'll scale the color of the surface not based on its orientation, 
but on how far the surface point is located from the camera position. The parameters to the 
shader define two z coordinate values. Anything closer than the near value will be white, any 
thing farther away than the far value will be black, with the values in between rendered as shades 
of gray fading from white to black. This shader is called depth_fade. (We’ll define depth_fade 
on page 63.) 


declare shader 
color "depth fade" ( 


scalar "near", 
scalar "far" ) 
end declare 


Figure 4.30: Shader declaration of depth_fade (p.478) 


Rendering the same scene of cylinders using shader depth_fade in a material produces in the 
image in Figure 4.31. 
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material "depth" 
"depth fade" ( 
“Tear” 6, 


"far" -10 


) 


end material 


Figure 4.31: Using the depth_fade shader in a material 


We can use the output of the front_bright and depth _fade shaders as inputs to another shader. 
The scaled_color shader we defined on page 25 takes two colors as inputs. Since shaders 
front_bright and depth _fade produce colors for their results, we can use them to define named 
shaders we can use instead of explicit color values for the two parameters of scaled_color. As 
we saw in Section 4.4.3, once a shader has been named, it can be referenced using the equals sign 
(=), Prog 68, 2.4. Shader Graphs 


Scene file 


shader "shader depth" 
"depth fade" ( 
Named shader "near" 10, 
tar’ -1¢ 


shader "shader front" 
"Eront bright 4 


Named shader "tint" 1.05 1.05 1.05 


) 


Material 


ce material "front depth" 
Shader oo "Scaled color" ( 


: "base color" 


end material 


Figure 4.32: Shaders front_bright and depth_fade as parameter values for scaled_color 


Using the results of the front_bright and depth_fade as parameters to scaled_color for the  Prog68, 2.4. Shader Graphs 
material used with column scene produces the image in Figure 4.33. 
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material "front depth" 
"scaled color" ( 
"base color" = "Shader front", 


"scale factor" = "shader depth" 


) 


end material 


Figure 4.33: Rendered image using shaders as parameter values 


In material front_depth, we’re combining the colors from two shaders in a third shader. This 
kind of shader graph is similar in spirit to an image processing operation, and we can visualize 
the process by thinking of the individual shaders as rendering entire images that are combined 
by a shader. 
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scaled color 


Figure 4.34: Shader combinations as a compositing operation 


This is a simple example, of course. Any number of shaders can be connected in a graph, and 
the kinds of data can be anything used by shaders in mental ray—scalars, colors, vectors, even 
images, as we'll see when we write texture mapping shaders in Chapter 9. 
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[ae] "Soa 


shader 
Figure 4.35: A graph consisting of many connected shaders 


Without writing new shaders, we can connect shaders together to create something that is in 
principle just like a large shader, with many parameters and a resulting value. To make such a 
large graph easier to define and use, we can bundle up the graph’s shaders and give it a name. 
Such a bundle is called a Phenomenon in mental ray. 


4.6 Named shader graphs: Phenomena 


In the last section, the outputs of shaders served as inputs for the parameters of other shaders. Rend 278, 11.4. Shader 


We connected shaders front_bright and depth_fade as inputs to shader scaled_color. a 
Prog 68, 2.4. Shader Graphs 


front bright 


scaled color 


base_color 
scale factor 


Figure 4.36: Shaders connected in a graph 


In mental ray, we can treat a group of connected shaders as a unit by defining a Phenomenon. 
The Phenomenon is used in the scene file in the same way as a single shader, but it’s built out of Rend281, 11.5. Phenomena 
multiple shaders. Prog 70, 2.5. Phenomena 


Rend 283, 11.5.1. 
Phenomenon Interface 
Assignments 


Prog 71, 2.5.1. Phenomenon 
Interface Parameters 
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front_bright 


scaled color 


base _ color 


Figure 4.37: Shaders connected in a graph as part of a Phenomenon called front_depth 


In Figure 4.37, we’ve made a Phenomenon out of the shader graph in Figure 4.36. Some of the 
parameters of the shaders in the graph are treated as the inputs parameters to the Phenomenon, or 
the Phenomenon’s interface parameters. Here, tint, near and far are the interface parameters 
for our Phenomenon called front_depth. Even though they are parameters for two different 
shaders, the Phenomenon hides this distinction. The shader names and their associated definitions 
that comprise the shader graph within the Phenomenon are said to be encapsulated, or hidden 
from the scene file in which the Phenomenon is defined. In the Phenomenon declaration, any 
shaders defined in the scene file are not “visible” to the Phenomenon. Because of encapsulation, 
you can use simple (and intuitive) names for the components in your Phenomenon without 
worrying about the ambiguity caused by duplicating the names of other shaders in the scene file 
written by someone else. 


4.6.1 The components of a Phenomenon 


The declaration of the Phenomenon in the scene file is more elaborate than the declarations 
for shaders that we’ve looked at before. However, we can break up the Phenomenon into its 
components and describe them separately. Most of the syntax of these components will also be 
familiar to you by now. 
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Phenomenon name 


declare phenomenon 


Result type | 


coler ~*kinc”®, 


Interface parameters scalar "near", 
scalar “far” 


shader “front*" 
“frente Drignc® | 
"E1yt" = iunterfiace "tint" 


Shader definition 
) 


Shader "depth" 
"depth fade" ( 
Shader definition "near" = interface "near", 
"far" = interface "far" 


shader "combine" 
"scaled color" { 
Root shader "base color" = Siren"; 
“scale factor” = "depth" 


Primary root statement 


end declare 


Figure 4.38: Declaration of a Phenomenon 
A Phenomenon will at least have these components: 


Phenomenon name The name of the Phenomenon is like the name of a shader and is used in the 
same manner as the shader name in anonymous and named shaders. 


Result type The result type of the Phenomenon is the type of the value calculated by the root 
shader (see below). 


Interface parameters The interface parameters are declared and used in the same manner as 
shader parameters. 


Shader definitions The named shaders in the Phenomenon can refer to the values of the interface 
parameters using the interface keyword, as for the parameter tint in named shader 
front. Other shader parameters can either be constant values (like a color consisting of 
three numbers), or can refer to other shaders using the equals sign syntax for shader graphs. 


Root shader and the primary root statement One shader will be the first shader invoked when 
the Phenomenon is used in a material or shader. This shader is called the root shader, and 
is defined by the primary root statement. 


Once a Phenomenon has been declared, it can be used in a material just like a shader because 
the structure of the parameter list is identical to that of shaders. We can use our front_depth 
Phenomenon to render the image in Figure 4.39 and get the same result as Figure 4.33. However, 
all the control of the shaders in the graph of Figure 4.33 is available in the material. 


Rend 286, 11.5.3. 
Phenomenon Roots 


Prog 72, 2.5.2. Phenomenon 
Roots 
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material "column fade" 
'Front depth” { 
‘Cant’ 1,05 1.05 1.05, 
"near" 10, 
"far® =10 


) 


end material 


Figure 4.39: Using the Phenomenon in a material 


4.6.2 Defining a material as a Phenomenon 


Prog 70, 2.5. Phenomena The type of Phenomena we defined in the previous section takes the place of shaders. Those shader 
Phenomena can calculate and return the same types of values as shaders, such as colors, vectors 
Prog 73, 2.5.2. Phenomenon and scalars. Material Phenomena share the same structure as shader Phenomena, but define a 
— mechanism for creating materials instead. These materials can differ based on the Phenomenon’s 
interface parameters. In the same way that a shader Phenomenon is an encapsulated shader, the 
material Phenomenon is an encapsulated material. Material Phenomena can be very useful in 
combining shaders of different types required by more complex effects (like global illumination) 

into the procedural interface of a shader call. 
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declare phenomenon 


Material type declaration "global_diffuse" ( 
color “@ittuge" detauit 1 i i; 
array Tight. "“Lignte" 
) 
shader "indirect" 
"average radiance" () 
shader "indirect_diffuse" 
"scaled color" ( 
"base color” = interface: "diffuse", 
"scale factor" = “indirect” 


material "lambert _with_photons" 
"lambert" ( 
"diffuse" = interface "diffuse", 
"ambient" = "indirect diffuse", 
"lights" = interface "lights" 


Material definition ) 
photon 
"store diffuse photon" ( 
"diffuse color" = interface "diffuse" 
) 


end material 


Root material root material "lambert with photons" 


end declare 


Figure 4.40: Declaration of material Phenomenon global_diffuse that includes a photon shader 


The syntax for material Phenomena is very similar to the shader Phenomena. The components 
of the material Phenomena that are different from the shader Phenomena are outlined in 
Figure 4.40. 


Material type declaration The declaration syntax of a material Phenomenon only differs from 
a shader Phenomenon in the result type declaration, material. 


Material definition In addition to a shader network of the shader Phenomenon, the material 
Phenomenon includes the definition of a material element. All the various shader types 
that can be defined in a normal material can be used in the Phenomenon’s material definition. 
In this Phenomenon, a photon shader has been added to the material that uses the same 
input color as the lambert shader, the interface parameter diffuse. The photon shader 
creates a photon map used by shader average_radiance in indirect, one of the shaders 
in the Phenomenon’s shader graph. (We'll take a look at photon shaders in Chapter 16, 
“Light from other surfaces.”) 


Root material Like the shader Phenomenon’s root shader, the root material identifies the 
resulting value of the Phenomenon. For a material Phenomenon, this value produced 
by the Phenomenon is a material element in the scene database, not simply a parameter 
datatype like a color. 


To use a material Phenomenon as the material for an object instance, a shader is defined from a 
material Phenomenon, supplied with values for its parameters. 


Prog 114, 2.7.4. Materials 


Rend 271, 11. Shaders and 
Phenomena 


Rend 272, 11.1. Declarations 


Rend 275, 11.2. Definitions 


Rend 277, 11.3. Shader Lists 


Rend 278, 11.4. Shader 


Graphs 


Rend 281, 11.5. Phenomena 


Prog 185, 3. Using and 
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shader "red" 
"global diffuse" ( 
“difftuse" 10 0, 
‘lights"®™ ("light inet") } 


instance "block inst" "block" 


material "red" 
transform 
1.81818 0 0 0O 
O 0 -1.81818 0 
0 1.81818 0 O 
-1.63636 0.545455 0 1 
end instance 


Figure 4.41: Using a shader created from a material Phenomenon for the material of an instance 


The shader red uses the material Phenomenon global_diffuse to create a shader definition that 
can serve as a material. This shader is then used in the block_inst element in the same way as 
a normal material. The photon shader required in the material for global illumination has been 
encapsulated within a simple, shader-like interface. 


4.7. The five shader usage types 


As we’ve seen in this chapter, a shader in mental ray can be used in one of five ways in the scene 


file: 


Anonymous Included in a material directly using the shader’s name and a list of parameters 
values. 


Named Included in a shader element defined in the scene file, and referenced later using the 
equals sign (=) followed by the name of the shader element. 


List As part of a list of shaders in a material, in which the previous shader’s result is passed to 
the next shader in the list. 


Graph Using one shader’s output value as the input to another shader’s parameter to form a 


shader graph. 
Phenomenon A shader graph bundled up with a name and a defined set of input parameters and 


an output serving the same function as a shader in the scene file. 


Now that we have an idea of how shaders are used in a scene in mental ray, we’ll take a look at 
how an individual shader is defined as a function in the C programming language. 


Part 2: Color 


1;wiold shes 


Chapter 5 


A single color 


As we saw in Chapter 3, a shader calculates some output value based ona standard set of input data Rend 11, 1.3. Shaders 
and the parameters chosen for the shader. Now we’ll see how these concepts are implemented in 


C. 


Material 


Shader 


result 


Figure 5.1: A model for shaders as a process with inputs and outputs 


5.1 The simplest shader model 


In this chapter we'll develop one of the simplest possible shaders, a C function called one_color 
that takes a single input parameter and uses that as its result value. For this, we won’t need to 
consider the state or the previous result. As Figure 5.2 suggests, the shader doesn’t so much 
calculate a color as just pass through the value passed in as a parameter. 


Material 


one color 


parameters 


Figure 5.2: Model of shader one_color 


Prog 198, 3.4. State Variables 
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5.2. The shader function in C 


Most of the mental ray shaders you will write share a common structure in many aspects: the 
argument signature, how parameters are accessed, and the way that the shader’s completion 
status is specified. Figure 5.3 is the C function for one_color with these common elements 


labeled. 


1. Shader name 


2 Return type | (RIGoIor sresuiy, 3 Result 
miState *state|, 4. State 
struct one color *params| ) 5. Parameters 


6. Parameter 


miColor *color = mi_eval_color(&params->color) ; 


evaluation 
result->r = color->r; 
7. Result result->g color->g; 
computation result->b color->b; 


result->a = color->a; 


8. Status return return miTRUE; 


Figure 5.3: The components of a shader 


1. Shader name The name of the shader used in the scene file is the same as the name of the 
shader function. 


2. Return type The status of the shader’s calculation upon completion is provided to mental 
ray through the return value of the shader function. The type of the value is miBoolean. 
Shaders typically return miTRUE, but miFALSE is sometimes returned to signal that no 
further calculation is necessary for that part of the rendering. (We’ll see an example of 
miFALSE in Chapter 13, “Shadows,” if the result of a shadow shader is black.) 


3. Result The resu/t argument is a pointer to the data calculated by the shader. The shader 
supplies a value to the caller of the shader by saving the result of the computation in this 
pointer. If the previous shader’s value is needed, then it will be available through the pointer 
when the shading function begins execution. 


4. State The current rendering state is available in the state argument. Much of the work 
we'll do in learning how to write shaders will be in exploring what parts of the rendering 
state are available through this argument and how we can use them. In this simple shader, 
however, we aren’t using the state structure; the output color is not dependent upon the 
state of the current point being rendered. 


5. Parameters The parameters for a shader are the inputs that you decided the shader needs. 
This is another big part in learning how to write shaders: deciding what input is needed 
from the scene to effectively control what the shader does. The parameters are contained 
in a structure that is typically defined in the source file that contains the shader. There is 
only one parameter for shader one_color, so its parameter structure is defined like this: 
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struct one_color { 


miColor color; 


bi 


Figure 5.4: Parameter structure declaration 


6. Parameter evaluation As we saw in Section 4.5, the output of one shader can be used as 
the value of an input parameter to another shader in a shader graph. In a sense, a shader 
can request a value from another shader when it uses that value for one of its parameters. 
But the values of all the input parameters may not be required—some of the parameters 
may disable a part of the shader code that make other parameters unnecessary. Conversely, 
more than one parameter value in the scene may acquire its value from the same shader. 


Rather than inefficiently executing a shader when its value is either unnecessary or has 
already been calculated, mental ray provides for control of parameter evaluation in a 
shader. The macro mi_eval_color from the mental ray API library is one example of a 
set of macros that provide access to a parameter’s value. As we'll see in the shader’s we'll 
write, a different macro is used for the various data types—mi_eval_integer for integers, 
for example. 


7. Result computation The main body of a shader uses the state, the parameters and possibly 
the previous result to calculate the shader’s result value. In this example, the calculation is 
trivial; we’re just assigning the result to the value of the single input parameter. 


8. Status return The miBoolean value described above is returned to indicate the completion 
status of the shader. For simple shaders, the return value will typically be mi TRUE. However, 
the status will be used by mental ray when further computation is no longer necessary, for 
example, when a ray strikes an area that is fully in shadow. 


Though this is one of the simplest shaders you can write, these components will be found in 
almost all of the shaders in this book. 


5.3 Theshader source file 


A shader function is saved ina C source file and compiled to produce a library module that mental 
ray loads at runtime. Multiple shaders can be collected in a single source file to create a library 
of related shaders. This is the structure behind the standard mental ray shader libraries. 


For the shaders we’ll write in this book, we’ll usually specify one shader per source file. In the 
same way that the shader functions have a typical structure, we can think about a standard format 
for our shader files. 


Prog 232, 3.6. Parameter 
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Shaders 


Prog 186, 3.1. Dynamic 
Linking of Shaders 
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1. Library function 


declarations 
2. Version function int one color version(void) { return 1; } 
struct one color { 
3. Parameter structure miColor color; 


bs 


miBoolean one_color ( miColor *result, 
miState *state, 
struct one color *params ) 


miColor *color = mi_eval_color(&params->color) ; 
4. Shader function result->r = color->r; 

result->g = color->g; 

result->b = color->b; 

result->a = color->a; 

return miTRUE; 


Figure 5.5: The components of a simple shader source file 


1. Library function declarations Writing mental ray shaders is simplified by an extensive 
library of utility functions that provide everything from simple math functions to high- 
level functions that calculate rendering effects like shadows and irradiance. These functions 
are declared in the header files shader .h and geoshader . has part of the mental ray software 
distribution and define mental ray’s application programming interface, or API. Learning 
to write mental ray shaders is in large part the process of becoming familiar with this 
vocabulary. As we write shaders we’ll use more and more of the functions in the libraries 
supplied as part of mental ray. 


2. Version function As we saw in Chapter 4, the declarations of shaders used by the scene 
file contain a version number. The version function in the C source file allows mental ray 
to guarantee that the scene file declaration and the arguments of the C file are the same. 


3. Parameter structure The parameter structure is typically defined in the same source file 
as the shader function which uses it as a data type for its parameter argument. 


4. Shader function The function with the previous three elements in the file comprise a 
complete unit that can be compiled and loaded at render time by mental ray. 


Both the version number and the number and type of arguments need to agree between the shader 
source file in C and the scene file or mental ray will report an error when the shader is used during 
rendering. The version function and the parameter structure in the C file are combined in the 
shader declaration in the .mi scene file. 
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declare shader 
color "one color" ( 
color "color" 


int one color version(void) { return 1; } 


struct one color { 
miColor color; 


) 
version 1 
end declare 


C source file Scene file 


Figure 5.6: Relationship of C parameters to scene file declaration 


Each shader parameter type in the .mi scene file has an equivalent C data type. This translation Prog 230, 3.5. Shader 
between mi and C data types is listed in Figure 5.3. nacaeiicies Dice arate 


.m1 syntax C syntax 

boolean miBoolean 

integer milnteger 

scalar miScalar 

vector miVector 

transform miMatrix 

color miColor 

string miTag of a char* 

scalar texture miTag of an miFunction or milmg_image 
vector texture miTag of anmiFunction or milmg_image 

color texture miTag of an miFunction or milmg_image 

light miTag of anmilnstance for a light or a light group 
material miTag of an miMaterial 

geometry miTag of an mi0bject, miGroup, or miInstance 
lightprofile miTag of anmiLight_profile 

data miTag of an miUserdata 

shader miTag of an miFunction 

struct struct 

array mi-type Three fields: 


int — offset from base address for first element 
int — number of elements in array 


C-type[1] — base address of an array of C-type 


Figure 5.7: Data types in the .mi scene file and their equivalent C declarations 


Because mental ray may be rendering a scene on more than one computer, pointers to memory 
are not allowed. References to complex data structures are therefore provided by tags, which Prog 320, 3.26.1. DB 
keys 1 h datab We'll h d lights in | pnenas 
serve as keys into the scene database. (We’ll see tags when we use textures and lights in later 
chapters.) Memory considerations also require that arrays of data be represented in C by three 
fields in the parameter struct. The array .mi type is often used for lists of lights, and we'll first Prog 229, 3.5. Shader 
take a look at arrays in Chapter 12, “Light on a surface.” Paaraete Decleranans 


Like array, the struct type defines a parameter that contains multiple values, and is a direct 
analogy to the struct composite type in C. We’ll use the struct type in Chapter 10 when the 


Prog 114, 2.7.4. Materials 
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Store contour shader returns multiple values. (See Figure 10.7.) 


5-4 Using a shader in a material 


To use shader one_color to render a scene, we supply values for its parameters and include in it 
a material. In Figure 5.8, shader one_color is included anonymously in three different materials 
for the three object instances. 


material "yellow" 
"one color" ({ 
Neoler", & oi 
end material 


material "blue" 
"one color" 


"color" 
end material 


material "red" 
"one color" 
feo lor" 

end material 


Figure 5.8: A single color for the entire object defined by shader one_color in the material 


Throughout the book, we’ll be rendering images like Figure 5.8 using the shaders developed in 
each chapter. Accompanying the image will be a fragment of the scene file that describes how 
the shader is used, or includes other parts of the scene file that will affect the final image. All the 
rendered images are collected in Appendix A beginning on page 457 and serve as a visual index 
to the various techniques we’ll develop. 


5-5 Shader programming style 


To simplify the structural diagram of shader one_color, the three arguments to the shader 
function were placed on different lines. To shorten the source code examples throughout the 
book, most shaders will be shown with their arguments all on the same line. 


miBoolean one color ( 
miColor *result, miState *state, struct one color *params ) 


miColor *color = mi_eval_ color (&params->color) ; 
result->r = color->r; 


result->g = color->g; 
result->b = color->b; 
result->a = color->a; 
return miTRUE; 


Figure 5.9: Putting the standard shader arguments on a single line 


But we can go further than just rearranging the code to shorten it. The size of a variable of type 
miColor is known by the compiler in advance (a C struct containing a field for each of the red, 
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green, blue and alpha channels). Argument result points to previously allocated storage, so we 
can directly assign the value of mi_eval_color to it. (In C programming jargon, *result can 


serve as an L-value, the left side of an assignment statement.) 


miBoolean one color ( 


{ 


miColor *result, miState *state, struct one color *params ) 


miColor *color = mi_eval_color(&params->color) ; 
*result = *color; 
return miTRUE; 


Figure 5.10: Direct assignment of the evaluated parameter to a local variable 


Now it’s clear that in this simple shader function, the use of the local variable color is unnecessary. 
We can make the assignment of the evaluated parameter to the result argument directly. 


miBoolean one color ( 
miColor *result, miState *state, struct one color *params ) 


*result = *mi_eval_ color (&params->color) ; 
return miTRUE; 


Figure 5.11: Direct assignment of the evaluated parameter to the shader’s result 


The direct assignment of the evaluated parameter to the result pointer is a matter of efficiency, 
whereas the textual arrangement of the shader arguments can be determined by personal taste. 
Throughout the code examples in this book, I have tried to balance brevity (and my attempt to 
keep shader source code to a single page in length) with clarity. You may prefer a different C 
programming style, either due to personal taste or the requirements of a style guideline in a group 
project. 


5-6 Basic issues in writing shaders 


Though one_color is a very simple shader, we’ve seen most of the issues that are important when 
writing shaders of any level of complexity: 


1. The shader parameter declarations in the .mi language and as a C struct; 

2. The version function in C and the corresponding version statement in the .mi declaration; 
3. Using functions and macros in the mental ray API library; 

4. The body of the shader function that does the primary work of the shader; and 

5. The use of the shader in an element of a scene file. 


Now that we have a basic model for shader implementation in C, the following chapters will 
look at other simple ways of creating the color the material provides to object instances. 


Prog 226, 3.5. Shader 
Parameter Declarations 


Prog 235, 3.7. Shader 
Versioning 


Prog 307, 3.26. Functions for 
Shaders 


Prog 413, 3.31. Example 
Scene with Custom 


Shader 
Prog 191, 3.3. Shader Type 
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Chapter 6 


Color from orientation 


In the previous chapter, we defined a shader that produced a constant color. Typically, the color 
of a surface will be dependent upon a number of factors—its shape, where it is, images that are 
used to define its color, and, as we’ll see in the next part of the book, Light, how the color of the 


surface can be represented by a simulation of the physics of illumination. Rend 177, 7. Caustics and 
Global Illumination 


6.1 The representation of rendering state: miState 


For most shaders, the second argument is a pointer to a variable of type struct miState that Prog198, 3.4. State Variables 
describes the current state of mental ray. By convention (so that various predefined macros will 

work correctly), this argument is always called state, and when we refer to the “state” in a 

shader, we’ll be talking about this pointer to the miState structure. The state consists of over 

fifty fields, some of which, like camera, are also structs, with further information contained as Prog 200, 3.4.1. Frame 
subfields of miState. Figure 6.1 lists a few of the most commonly used fields in miState. 


state->org Start point of the ray 
state->point The ray’s intersection point 
state->dir Direction of the ray 
state->dist Length of the ray 
state->normal Interpolated surface normal 


state->normal_geom Geometric surface normal 


Figure 6.1: Some commonly used fields in the miState struct 


The complete set of fields in miState can be divided into six conceptual categories: 


Frame Camera information and rendering options 
Image samples Image coordinates and current shader description 
Rays The current ray being cast 
Intersection ‘The intersection point currently being rendered 
Textures, motion, derivatives ‘Texture mapping information for the current intersection point 
User fields Storage of user-defined data for use by shaders 


A single shader may only use a few fields in miState. Knowing what kind of information is 
available in the state is an important part of learning how to write mental ray shaders. 


Prog 210, 3.4.4. Intersection 


Prog 232, 3.6. Parameter 
Assignments and mi-eval 
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6.2 Ashader based on surface orientation 


We want to write a shader in which surfaces that face the camera are brighter than surfaces that 
face away from it. Using this shader, we can get an idea of the shape of an object but with a 
simple scene setup (without using lights). 


We'll call this shader front_bright. We’ll base the color the shader defines on the orientation, 
but we’ll allow that value to be scaled by the color parameter tint. This is the declaration of 
front_bright: 


declare shader 
eolor "Eront: bright” { 


color "tint" default 111 ) 
end declare 


Figure 6.2: Shader declaration of front_bright (p.476) 


To find out about the orientation of the surface, we'll use the dot_nd miState field in the 
Intersection category in the state. This value is the dot product of the surface normal, a vector 
that is 90 degrees to the surface at the point being rendered, and the direction from the camera. 
This dot product varies from 0.0 (at the edges) to -1.0 (when the surface directly faces the camera). 
By negating this value, we have a scale factor that indicates to what degree a surface points toward 
the camera. 


Here’s the source code for shader front_bright. In shader code examples, the page number of 
the full source code listing in Appendix B (beginning on page 475) is included in the caption of 
the figure. 


struct front bright { 
miColor tant; 


miBoolean front_bright ( 
miColor *result, miState *state, struct front bright *params ) 


miColor *tint = mi_eval_ color (&params->tint) ; 
miScalar scale = -state->dot_nd; 

result->r tint->r * scale; 

result->g = tint->g * scale; 

result->b tint->b * scale; 

result->a 1.0; 

return miTRUE; 
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Figure 6.3: Shader source of front_bright (p.476) 


The parameter tint is acquired with mi_eval_color in line 8. The dot_nd field in line 9 defines 
the variable scale. The color tint is modified by variable scale in line 10-12 for the result 
color of the shader. By defining the alpha value to 1.0 in line 13, we have specified that the object 
is opaque. 


We use front_bright to create a material called front for the rendering in Figure 6.4. Because 
no value is passed for the tint parameter (the argument list is empty and is represented by “()”), 
the default value specified in the shader declaration is used for it, a value of 11 1. 


6.4 Other fields in miState 59 


material "front" 


"Eremt bright” «() 
end material 


Figure 6.4: Using shader front_bright without explicit parameter values to define material front 


6.3 Passing parameters to a shader 


By using a color for the tint parameter, we can see that the surface orientation can be used to 
change the intensity of an arbitrary color. 


tiaterial "front. red" 
Pirro brighn” 1, "Cant? 
end material 


material "front: yellow" 
‘front brignc’’ | "tint" 
end material 


material "front blue" 
“front bragac™ ( 7 fint" 
end material 


Figure 6.5: Three calls to shader front_bright with different values for the tint parameter 


6.4 Other fields in miState 


The dot_nd value in the state is only one of many variables in the Intersection category. Not all 
variables are useful in all shader types, but it is useful to see the kinds of data that are available to 
shaders. Figure 6.6 shows the data types, names and descriptions of these variables. 


Prog 208, 3.4.4. Intersection 
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Type 

miTag 
miUint 
miTag 
miTag 
miScalar [4] 
miVector 
miVector 
miVector 
miCBoolean 
miScalar 
double 
miTag 
void* 

int 

double 
miScalar 
miScalar 


Name 


refraction_volume 
label 
instance 
light_instance 
bary 

point 

normal 
normal_geom 
inv_normal 
dot_nd 

dist 

material 

pri 

pri_idx 
shadow_tol 

ior 

ior_in 
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Description 


Volume shader for refraction 
Object label for label file 
Instance of object 

Instance of light 

Barycentric coordinates 
Intersection (ray end) point 
Interpolated normal at point 
Geometry normal at point 

True if normals were inverted 
Dot product of normal and dir 
Length of the ray 

Material of hit primitive 
Identifies hit box 

Identifies hit primitive in box 
Safe zone to prevent self-shadows 
Index of refraction of medium 
Index of refraction of previous medium 


Figure 6.6: Intersection information in the miState struct 


The dot_nd variable is the dot product of the state’s normal and dir variables. The dir variable is 


Prog 204, 3.4.3. Rays 


Type 
miState*x 
miState* 
miRay_type 
miCBoolean 
miVector 
miVector 
float 
miTag 
mitag 

int 

int 

char 


Name 


parent 

child 

type 

scanline 

org 

dir 

time 

volume 
environment 
reflection_level 
refraction_level 
face 


in the Rays category of state variables. Figure 6.7 lists the other variables in this category. 


Description 


State of parent shader 

State of child shader 

Type of ray 

Intersection is due to scanline algorithm 
Start point of the ray 
Direction of the ray 

Shutter interval time 
Volume shader of primitive 
Environment shader 
Current reflection ray depth 
Current refraction ray depth 
Facing direction of primitive 


Figure 6.7: Ray information in the miState struct 


When writing shaders, you can look up state variable names and data types in the HTML version 
of Programming mental ray provided with the mental ray software distribution. However, 
you should also become familiar with the definition of mental ray data types like miState by 
examining the header file that contains their definitions, shader.h. Any questions about the 
documentation of data types can always be resolved by consulting the header files. 
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6.5 Calculation of surface orientation 


Though dot_nd has already been calculated for use in shaders, we could have calculated it 
explicitly, as in the following shader. 


struct front bright dot { 
miColor tint; 
iz: 


miBoolean front bright dot ( 
miColor *result, miState *state, struct front bright dot *params ) 


i 
2 
3 
o 
5 
6 
fi 
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miColor *tint = mi_eval_color(&params->tint) ; 

miScalar scale = -mi_vector dot(&state->normal, &state->dir) ; 
result->r = tint->r * scale; 

result->g = tint->g * scale; 

result->b = tint->b * scale; 

result->a = 1.0; 

return miTRUE; 
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Figure 6.8: Shader source of front_bright_dot (p.477) 


In line 9 the dot product between state->normal and state->dir is calculated using the 
mental ray library function, mi_vector_dot. Shader writing in mental ray is based on both 
the information available in the rendering state and the calculations that can be made using the 
mental ray API library. As we write shaders, we’ll be using a wide variety of these library 
functions, from mathematical utilities like mi_vector_dot to functions that calculate complex 
lighting simulations. 


6.6 Shaders as analysis tools 


By basing our calculation in front_bright on the surface orientation, we get an image that has 
an intuitive appeal—it’s as if there’s a light located right at the camera shining on the objects. 
But the calculation of surface color in a shader is arbitrary. We can use shaders not just for the 
creation of final imagery, but as tools for analysis in our scenes to be rendered. 


For example, we can treat the surface normal vectors as colors by treating the vector’s x, y and 
z components as the red, green and blue components of a color. Our shader that makes this 
interpretation is called normals_as_colors. It doesn’t use any parameters. 


declare shader 


color "normals_as_colors" () 
end declare 


Figure 6.9: Shader declaration of normals_as_colors (p.477) 


Since red is defined by the x direction, when we render the same scene as before we can see that 
the right sides of the objects are redder than the left sides, since the normals are pointing in the 
positive x direction there. 


Prog 349, 3.26.7. Math 
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material "normals" 


"normals as colors" 


end material 


Figure 6.10: Interpreting the surface normal vector as a color 


Even though the shader source code is very short, such a visualization can be very useful when 
checking models for inconsistencies in their surface geometry. 


miBoolean normals _as_colors ( 


miColor *result, 


{ 


miVector normal; 


mi vector to object (state, 
mi vector normalize (&normal) ; 


result->r 
result->g 
result->b 
result->a 


normal .x /'2.-0 + 
normal.y / 2.0 + 
normal.z / 2.0 + 
L.0s 


return miTRUE; 


miState *state, 


~ 5} 
; SF 
oe 


void *params ) 


&normal, &state->normal) ; 


Figure 6.11: Shader source of normals_as_colors (p.477) 


In lines 4-6, the vector components, which vary from -1.0 to 1.0, are scaled to the typical range 


for colors, 0.0 to 1.0. 


We'll develop shaders that adopt a similar analysis-based approach when we visualize the texture 
coordinate space of an object in Chapter 9, Color from functions. 


Chapter 7 


Color from position 


As we saw in the last chapter, the state parameter passed to shaders contains information about 
the current point being rendered. The state includes the current position of that point, stored 
in the state structure as state->point, of type miVector. We can compare this position to 
three-dimensional points passed as parameters to a shader to vary the color of an object. 


7.1 Intensity based on distance 


Shader depth_fade creates a gray-scale value based on the z position of the current point, scaling 
between the near and far values provided to the shader as parameters. Any z position nearer than 
near value will be white; any farther than the far value will produce black. 


Se eS Ocomera 


far near 


Figure 7.1: Intensity values defined by the distance from the camera 


In the shader, the near and far z values will be passed as scalar parameters to the shader: 


declare shader 
color “depth fade" { 


scalar "near", 
scalar "far" ) 
end declare 


Figure 7.2: Shader declaration of depth_fade (p.478) 


The depth_fade shader determines the current z coordinate value from state->point in line 12 


of the shader: 
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struct depth fade { 
miScalar near; 
miScalar far; 


hi 


miBoolean depth fade ( 


{ 


miColor *result, miState *state, struct depth fade *params ) 


ONAN MFP WN BP 


\o 


miScalar near = *mi_eval_scalar(&params->near) ; 
miScalar far = *mi_eval_scalar(&params->far) ; 
miScalar zpos = state->point.z, factor; 
if (zpos > near) 

factor = 1.0; 
else if (zpos < far) 

Tactcor = 0.0; 
else 

factor = (zpos - far) / (near - far); 
result->r = result->g = result->b = factor; 
return miTRUE; 
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Figure 7.3: Shader source of depth_fade (p.478) 


After acquiring the parameter values near and far, the z position is used to define factor, the 
fractional distance from near to far expressed as a number from 0.0 to 1.0 in lines 12-17. 


material "depth" 
"aepEeh fade" 


"near" 1 
"Far" <1. 
end material 


Figure 7.4: Mapping the z coordinate of a point on a surface to a grayscale value 


7.2. Interpolating between colors based on distance 


The shader depth_fade_tint is similar to the previous shader, but the factor value is used to 
interpolate between two colors provided as parameters to the shader. 


7.2 Interpolating between colors based on distance 


declare shader 
color "depth_fade tint" ( 
scalar "near", 


color "nearocoiteér* default 1 i: fF, 

scalar "far", 

color "far golor’@ default 0 0.0 ) 
end declare 


Figure 7.5: Shader declaration of depth_fade_tint (p.478) 
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Based on the distance between near and far different amounts of the two colors will be blended 


together. 


struct depth fade tint { 
miScalar near; 
miColor near_color; 
miScalar far; 
miColor far_color; 


bi 


miBoolean depth fade tint ( 


{ 


miScalar near = *mi_eval scalar (&params->near) ; 


BRR 
NPFPOWMAIHDUOBRWNPKB 
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miScalar far = *mi_eval_scalar(&params->far) ; 


14 
15 


miScalar zpos = state->point.z, factor; 


if (zpos > near) 
rFactor = 1.0; 

else if (zpos < far) 
factor = 0.0; 
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© ~J 0) 


fh 
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else 
factor = (zpos - far) / (near far); 


DO NN ND 
WhO EF oO 


result+sr near color->r * factor fax color-sr** 
result->g near.color-sg * factor far color-sg * 
result->b near color->b * factor far color-sb * 
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return miTRUE; 
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Figure 7.6: Shader source of depth_fade_tint (p.478) 


miColor *near_ color = mi_eval_color(&params->near_color) ; 


miColor *far color = mi_eval_color(&params->far_color) ; 


Rend 553, C.7. Data 


Conversion 


miColor *result, miState *state, struct depth fade tint *params ) 


factor) ; 
factor) ; 
factor) ; 


In lines 17-22 we calculate the depth factor as before, but then use this fractional value to blend 
between the colors in lines 24-26. Rendering with blue and yellow as the two colors produces 
an image in which the color changes from one color to the other through the space of the 


picture: 


Prog 307, 3.26. Functions for 
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material "depth" 
"depth fade tint" ( 
"near" 1.25, 


"near color" 1 1 

"far" -1.i5, 

"far color" 0 0 
end material 


Figure 7.7: Blending between two colors based on the z coordinate of a point on a surface 


7-3 Clarifying the shader with auxiliary functions 


Defining auxiliary functions can clarify the method being used in the shader. In this chapter 
we'll begin to develop a library of auxiliary functions that will make the strategies of the shaders 
clearer from their code. All of these functions will be named with a prefix of miaux ("mental 
images auxiliary," in the same spirit as the mi_* functions in the mental ray library), and will be 


consolidated in a library. 


First we'll define a function to rescale a value from one range to another, so that the proportional 
relationships of the new values match those of the original: 


original range 


ZANS 


| 


proportional fit 
to new range 


Figure 7.8: Converting from one scale to another 


This basic function will be useful when we want define a relationship between scales of arbitrary 
type, like the mapping from the near and far parameter values to a normalized range of 0.0 to 


1.0. 


double miaux_ fit ( 
double oldmin, double oldmax, 


return newmin + ((v - oldmin) 


double newmin, double newmax) 


(oldmax - oldmin)) * (newmax - newmin) ; 


Figure 7.9: Function miaux_fit 


Since we’re blending two colors based on a weighting factor, we'll define a function to perform 


this color blending: 


7-3 Clarifying the shader with auxiliary functions 67 


double miaux_blend(miScalar a, miScalar b, miScalar factor) 


{ 


return a * factor + b * (1.0 - factor); 


} 


Figure 7.10: Function miaux_blend 


We can use the same weighting factor for all of the color components: 


void miaux_blend_colors(miColor *result, 


{ 


miColor *colorl, miColor *color2, miScalar factor) 


result->r miaux_blend(colorl->r, color2->r, factor) ; 
result->g miaux blend(colorli->g, color2->g, factor) ; 
result->b = miaux_blend(colorl->b, color2->b, factor) ; 


Figure 7.11: Function miaux_blend_colors 


Using these functions to rewrite shader depth_fade_tint, we get a much clearer picture of the 
relatively simple operation that the shader performs: 


ONAN MF WD FP 


\O 


10 
cies 


HoH 
Wd 


PRR PR 
OINHFH us 


NO FR 
om <e) 


struct depth fade tint 2 { 


hi 


miScalar near; 
miColor near color; 
miScalar far; 
miColor far! color; 


miBoolean depth fade tint 2 ( 


{ 


miColor *result, miState *state, struct depth fade tint 2 *params ) 


miScalar near = *mi_eval_ scalar (&params->near) ; 

miColor *near_color = mi_eval_color(&params->near_color) ; 
miScalar far = *mi_eval_scalar(&params->far) ; 

miColor *far_color = mi_eval_color(&params->far_color) ; 


miaux blend colors(result, near_color, far_color, 
Miaux fit (state-spoint.z, far, near, 0. 


return miTRUE; 


Figure 7.12: Shader source of depth_fade_tint_2 (p.479) 


Now the multiple-line implementation of color blending in the previous shader is expressed more 
clearly by a single function call in lines 16-17. 


Consolidation of the shader code may also be possible by using parameter values directly if they 
are only required once in the shader. 
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struct depth fade tint 3 { 
miScalar near; 
miColor near color; 
miScalar far; 
micolor far color; 


bi 


miBoolean depth fade tint 3 ( 
miColor *result, miState *state, struct depth fade tint_3 *params ) 
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miaux_ blend colors (result, 
mi eval _ color(&params->near_color), 
mi_eval_color(&params->far_color), 
miaux fit(state->point.z, 
*mi_eval_ scalar(&params->far), 
*mi_eval_ scalar (&params->near) , 
0.8, Labs) ys 


ao 
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return miTRUE; 


Figure 7.13: Shader source of depth_fade_tint_3 (p.480) 


Now the use of local variables that were only used once in miaux_blend_colors have been 
replaced by the direct call to the mi_eval macros. The names of the fields of the depth_fade_tint 
struct are clear enough so that values passed to the function are still readily understood. 


Perhaps, however, we’ve gone too far and the previous version more clearly expresses the action 
of the shader. Any implementation of a shader should be based on a structure that most clearly 
describes its intention to another programmer. This structure will be some combination of 
common sense, individual taste, and the stylistic restrictions often required by a group effort. 
Optimizations (for example, replacing inner-loop function calls with the function body itself) 
are much more productively performed once the more difficult work of shader design (and 
debugging!) has been completed. Such optimizations, however, should be carefully considered— 
in a month, you may find yourself to be that “other” programmer, grateful to the original author 
for the care that was taken in the clarity of the shader’s design. 


Chapter 8 


The transparency of a surface 


In previous chapters, we have used variables in the state struct to calculate the color of the 
surface. We’ve also used a few of the mental ray library functions, like the mi_eval functions for 
parameters, and some utility functions, like mi_vector_dot. In this chapter, we use a function 
that examines the rendering environment through ray tracing. 


8.1 Using the API library to trace a ray 


In its calculation of color, the primary shader in the material can also examine the environment 
through API library functions that explicitly trace rays. Calculating the transparency of an object 
requires that we continue the ray from the camera as long as we encounter transparent objects 
along the path of the ray. 


The library function mi_trace_transparent can be called in a shader if the current object is 
considered to be transparent. As additional objects are encountered by the ray, they may also 
have shaders that include transparency. When the ray encounters an opaque object or leaves the 
scene entirely, the accumulated set of color values encountered by the ray can be blended together 
for the final sample color. 


Figure 8.1: Ray intersections in the calculation of the transparent value 


We’ll define a shader called transparent that specifies as parameters the base color of the object 
as well as its transparency. The transparency will be specified as a color as well. 
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declare shader 
color "transparent" ( 


color "color" default 11 i1 1, 
color "transparency" default .5 
end declare 


Figure 8.2: Shader declaration of transparent (p.481) 


In shader transparent, we are beginning to conditionalize the execution of the shader to make 
the shader more efficient. If the transparency value is 0.0—the object is completely opaque—we 
don’t need to spend any time figuring out what’s behind it. 


struct transparent { 
miColor color; 
miColor transparency; 


bi 


miBoolean transparent ( 
miColor *result, miState *state, struct transparent *params ) 
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miColor *transparency = mi_eval_ color(&params->transparency) ; 
if (transparency->r == 0.0 && transparency->g == 0.0 && 
transparency->b == 0.0 && transparency->a == 0.0) 
*result = *mi_eval_ color (&params->color) ; 
else { 
mi trace transparent (result, state) ; 
if (!(transparency->r == 1.0 && transparency->g == 1.0 && 
transparency->b == 1.0 && transparency->a 1.0)) { 
miColor *color = mi_eval_color(&params->color) ; 
miColor opacity; 
opacity.r = 1.0 - transparency->r; 
opacity.g = 1.0 - transparency->g; 
opacity.b = 1.0 - transparency->b; 
opacity.a = 1.0 - transparency->a; 
mi opacity set(state, &opacity) ; 
result->r = result->r * transparency->r + color->r * opacity.r; 
result->g = result->g * transparency->g + color->g * opacity.g; 
result->b = result->b * transparency->b + color->b * opacity.b; 


} 


return miTRUE; 


Figure 8.3: Shader source of transparent (p.481) 


In lines 10-11, we check to see if all the channels of the transparency parameter are 0.0. If they 
are, then the object is opaque, and the shader sets the result argument to the value of the color 
parameter. Since the miColor type is a struct of four miScalar types and its size is known at 
compile time, we can copy the value in a single assignment statement. 


If there is a non-zero transparency value, then we execute the else clause in lines 13-27. The API 
library function mi_trace_transparent sends a ray in the same direction and stores the resulting 
color in result. Note that this is a potentially recursive shader call—if the ray strikes another 
instance with a material that contains this transparency shader, then mi_trace_transparent will 
be called in it, and so on. In Figure 8.1, if all three objects instances use transparent as their 
material shader, then the shader could be called six times, depending upon the parameter settings 
in each material. 
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Now that we have the color produced by continuing the ray stored in result because of line 14, 
we can think of it as the background color that will be blended with the color of the object 
defined as parameter color. We already acquired the value of parameter color in line 12—why 
do it again here? Why not create a local variable for the entire shader, say, after line 9? 


Remember that the value of a color parameter may not be an explicit set of numbers in the scene 
file; using shader referencing as we saw in Section 4.3.2, the parameter value might be the result of 
some other shader call, which itself could execute a complex function based on further shader calls 
used as parameter values for it, and so forth, back any number of levels in the shader graph. The 
mi_eval_* macros allow you to efficiently defer the evaluation of the potential shader graph of a 
parameter until you actually need that value. The function is, after all, a normal C function, so its 
arguments are evaluated before its body is executed. The parameter struct only contains pointers 
to the parameter values; it’s the mi_eval_* macros that do the actual evaluation. That’s why we 
have both line 12 and line 17—we won’t need the value of the color parameter if the object is 
completely transparent (the conditional in lines 15-16), since we’ll just use the background color 
in that case. 


Once we’ve jumped through all those hoops, the blending of the colors in lines 19-26 is based on 
the same ideas as our depth_fade shader. However, we’ve assumed throughout this shader that 
were tracing rays to calculate values. We can, however, change the way that mental ray renders 
a scene in the options block by using an optimized version of scanline rendering called the 
rasterizer. The redundant specification of opacity in line 23 by the API function mi_opacity_set 
defines the transparency value that will be used by the rasterizer. 


Rendering a scene with the transparent shader, we can see the accumulation of color that results 
from the recursive call to mi_trace_transparent. (I’ve put a white square in the background so 
we can more easily see the transparency effects.) 


material "red transparent" 
"transparent" ( 
"eolor”™ 1 .4 4, 
"transparency" .7 .7 .7 ) 
end material 


material "yellow_transparent" 
"transparent" ( 
feoer” 2d. «%; 
"transparency" .7 .7 .7 ) 
end material 


material "blue transparent" 
"transparent" ( 
"color™ .4 .4@ I, 
"Cransparency"™ .7 
end material 


Figure 8.4: Three objects with transparency 


But something seems to be wrong here; the blue sphere is transparent, but we can’t see the 
red cylinder through it. The transparency value in ray tracing is also dependent upon the trace 
depth, a control provided over the mental ray core that can limit the number of times a ray 
is transmitted or reflected. By default, a ray will return a final value to a shader after two 
transmissions (transparency or refraction) and two reflections. As we can see from Figure 8.1, 
two transmissions take us to the blue sphere, but no farther. That’s why it looks opaque. 
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We can change the trace depth in the options block. The arguments to the trace depth 
command are the maximum number of reflections, the maximum number of transmissions, 
and the maximum total of the two. In Figure 8.5, we increase the number of transmissions to 
6—now we can see the red cylinder through the blue sphere. 


options "opt" 
object space 
SCtipraee sa va wk 
samples 0 2 
trace depth 0 6 6 
end options 


material "red transparent" 
"transparent" ( 
"oolor"™" 1 .4 .4, 
"Eraneparency" .7 .7 .7 } 
end material 


material "yellow _ transparent" 
"transparent" ( 
‘eq tar™ ba -.4, 
\eransparency™ .7 «7 «7? ) 
end material 


material "blue transparent" 
"transparent" ( 
"color" .4 .4 1, 
"transparency" 
end material 


Figure 8.5: Adjusting the trace depth for transparency control 


If we set the transparency trace depth to zero, then there’s no transparency at all—the objects are 
opaque. 
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options "opt" 
object space 
Contrast .1 «1 «i i 
samples 0 2 
trace depth 0 0 0 
end options 


material "red _ transparent" 
"transparent" ( 
"ooLlOr" 1 .4 «4, 
"Cransparency" .7 .7 
end material 


material "yellow_transparent" 
"transparent" ( 
iealor"® 7 7 we, 
"Cransparency" .7 ./ 
end material 


material "blue transparent" 
"transparent" ( 
‘color .4 .4 1, 
"Cransparency™ .7 ./7 
end material 


Figure 8.6: A transmission trace depth of zero—opaque objects 


8.2 Functions as a description of a process 


Though we want shader functions to be as fast as possible, the way that a shader calculates its 
value can be clearer with the use of auxiliary functions that calculate intermediate values. In the 
previous chapter we defined miaux_blend to make the shader more easily understood. For our 
transparency shader, we’ll define some more functions for our growing miaux library. 


First, a simple function that returns a true or false value based on a comparison of the channels 
of a color with a given value: 


miBoolean miaux_all channels equal(miColor *c, miScalar v) 
if (c-sr == v && c->g == v && c->b == v && C->a == Vv) 
return miTRUE; 
else 


return miFALSE; 


Figure 8.7: Function miaux_all_channels_equal 


Unlike depth fading (in the previous chapter), we’re using the separate channels of a color to 
determine how the channels of two colors will be blended together. We’ll call this channel-specific 
blending miaux_blend_channels: 
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void miaux_blend_channels(miColor *result, 


{ 


miColor *blend_ color, miColor *blend_ fraction) 


result->r = miaux blend(result->r, blend_color-sr, blend _fraction->r) ; 
result->g = miaux_blend(result->g, blend color->g, blend fraction->g) ; 
result->b = miaux_blend(result->b, blend _color->b, blend fraction->b) ; 


Figure 8.8: Function miaux_blend_channels 


Blending channels is like using “transparency” and “opacity” together. We’ll create the opacity 
value by inverting the transparency: 


void miaux_invert channels(miColor *result, miColor *color) 


1 

2 { 

3 result->r = 1. color->r; 
os result->sg ; color->g; 
5 result->b . color->b; 
6 result->a ; color->a; 
7 


} 


Figure 8.9: Function miaux_invert_channels 


Using these functions, the basic idea behind our transparency shader is much easier to understand 
from the names of the functions themselves. Rather than comment a section of code to describe 
what it does—and risk the confusion that occurs when the code is changed but the comments are 
not—the code now documents itself. 


struct transparent modularized { 
miColor color; 
miColor transparency; 


i 


miBoolean transparent modularized ( 
miColor *result, miState *state, struct transparent _modularized *params ) 
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miColor *transparency = mi_eval_ color(&params->transparency) ; 


if (miaux_all_ channels equal(transparency, 0.0) ) 
*result = *mi_eval_ color(&params->color) ; 
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else if (miaux_all_ channels equal(transparency, 1.0) ) 
mi_ trace transparent (result, state) ; 


else { 
miColor *color = mi_eval_color(&params->color), opacity; 
mi_trace transparent (result, state) ; 
miaux_invert_ channels (&opacity, transparency) ; 
mi opacity set(state, &opacity) ; 
miaux_blend_channels(result, color, transparency) ; 


} 


return miTRUE; 
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Figure 8.10: Shader source of transparent_modularized (p.481) 
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Using the miaux auxiliary functions, I’ve also rearranged the logic of the shader from the original 
implementation in Figure 8.3. Now the three possibilities—fully opaque (lines 11-12), fully 
transparent (lines 14-15), or somewhere in between (lines 17-23)—are much clearer in the 
structure of the code itself. 


Throughout the shaders in this book, we’ll develop other miaux auxiliary functions that break 
apart the various components of a shader into manageable, more understandable pieces. In 
developing a complex shader, it may be quite difficult to determine what exactly is going wrong 
by looking at the final rendering. If we can prove to ourselves that the auxiliary functions we’ve 
written work as we intend, and that we’ve combined them in correct ways, then we can be much 
more confident about the validity of the shader’s final result. 


Chapter 9 


Color from functions 


So far, we’ve defined single colors for the surfaces of objects and used other aspects of the object 
(its orientation, for example) to create a variation of color. We can also use a mathematical 
function to define how the color varies across the object. For its arguments, this function will 
use numerical values associated with some aspect of the surface. In this case we say that there is a 
mapping from some surface parameter to the color value we are going to use in our shader. 


As a special case of a mathematical function, we can also use the pixel values of a digital image, 
called a texture, to define surface color in a shader. Some numerical aspect of the surface (its Rend57, 4.2. Texture 


position in space, for example) is used to determine what point in the texture we should use for i 
the resulting color value. Once again, we are mapping one value to another, in this case, some 1708177112. Texture 
apping and Texture 


numerical value to a pixel position in the texture, resulting in texture mapping. Files 


= 


Texture mapping 


Figure 9.1: Using an image to define the surface color of an object 


As we saw in Section 4.5, the parameter values for any shader can be supplied by another shader. 
We can write shaders that reference the colors of digital images, and use those shaders as inputs to Prog 245, 3.9. Texture 
the parameters of other shaders. This means that we don’t have to plan on any shader parameter pe 


Rend 51, 4. Surface Shading 


Prog 226, 3.5. Shader 
Parameter Declarations 
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using the data in a digital image in advance, which makes mapping from one value to another a 
very flexible technique. 


9.1 The texture coordinate system 


In order to describe the position of colors on the surface of an object, we can define a texture 
coordinate system for it. By convention, we can think of a two-dimensional axis containing point 
[0,0] in the lower left corner. Traditionally, the horizontal axis is called u, and the vertical axis is 
called v. In mental ray, we don’t have a special data type for two-dimensional coordinates—we 
use the x and y fields of the miVector type to represent u and v. 
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Figure 9.2: A texture coordinate system and the resulting texture coordinates 


In our first shader exploring the texture coordinate system, we will treat these uv coordinate 
values not as positions on the surface, but directly as color values. This lets us visualize how the 
uw and v values vary across the surface. We’ll associate red with u and green with v. Combining 
them, we get yellow in the upper left corner of our texture coordinate system. 


U value as red V value as green U and V together 


Figure 9.3: Position in the uv coordinate space interpreted as color 


We'll define a shader that turns wv coordinates into colors, called show_uv. To provide for separate 
control for w and v in show_uv, we'll define Boolean parameters that can have either on or of f 
values in the scene file. By default, both u and v will be used, so the resulting image will be some 
combination of black, red, green and yellow. 
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declare shader 
color "show_uv" ( 


boolean "u" default on, 
boolean "v" default on ) 
end declare 


Figure 9.4: Shader declaration of show_uv (p.482) 


Rendering the cube and cylinder with both uw and v displayed, we can see how the texture 
coordinates change across the surfaces of the objects. 


material "uv" 


"show_uv" () 
end material 


Figure 9.5: The two-dimesional texture coordinates of a surface mapped to red and green values 


How do we access the texture coordinates of a surface? First, the texture coordinates values must 
be associated with individual vertices in the polygon or control points in the implicit surface. 
This is typically done by the modeling program that has generated the scene file. (In Chapter 19, 
we'll see how this can be done in an geometry shader.) The set of texture coordinates create a 
texture space. A surface can define 63 different texture spaces. These different spaces are accessed 
in the miState structure through the tex_list field, which is an array of type miVector. In 
the two-dimensional case, the x and y fields in the miVector type can be thought of as uw and v, 
respectively. 


For example, the show_uv shader in Figure 9.6 uses state->tex_list [0], the first texture space, 
associating the x field of the miVector with red and the y field with green. 
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struct show uv { 
miBoolean u; 
miBoolean v; 


ha 


miBoolean show_uv( 
miColor *result, miState *state, struct show_uv *params) 
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result->r = result->g = result->b = 0; 
if (*mi_eval_ boolean (&params->u) ) 
result->r = state->tex list[0] .x; 
if (*mi_eval_ boolean (&params->v) ) 
result->g = state->tex_list[0] .y; 
return miTRUE; 
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Figure 9.6: Shader source of show_uv (p.482) 


In lines 11 and 13, you can see the first texture space referenced with state->tex_list. In 
this simple shader we’re assuming that state->tex_list.x and state->tex_list.y always 
have values between 0.0 and 1.0, inclusive. Because mi_eval_boolean returns a value of type 
miBoolean, we can use it directly in lines 10 and 12. 


9.2. Quantizing the texture coordinates 


In shader show_uv, the red and green representations of the texture space vary smoothly because 
of the interpolation of the texture coordinates defined at the vertices. However, to get a better 
sense of the rate at which the interpolated values change across the surface, it is useful to create 
bands of color by quantizing the interpolated texture coordinates. 


U value as red V value as green U and V together 


Figure 9.7: Quantized texture coordinate values as colors 


To describe how many bands for the uw and v directions, we'll change our boolean arguments in 
shader show_uv to type integer. This new shader we’ll call show_uv_steps. If the value is zero 
for either parameter, then that coordinate is not shown, as if we had specified off in the previous 


shader. 


9.2 Quantizing the texture coordinates 


deciare shader 
color "show_uv_steps" 
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integer "u_count" default 4, 
integer "¥ count” default 4 } 


end declare 


Figure 9.8: Shader declaration of show_uv_steps (p.483) 


Now by specifying a value of 8 for both u_count and v_count, we can more clearly see the 
difference in the way that the texture space has been mapped to the top and sides of the two 


objects. 


material "uv" 
"show_uv_steps" ( 
"YW count” 8, 
'y GouneE” 6B ) 
end material 


Figure 9.9: Banding effect that demonstrates the scale of the texture space 


Since we need to create the banding effect for both uw and v, we'll define a function called quantize 
and call it for the calculations of red and green. 
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struct show _uv_steps { 
miInteger u_count; 
miInteger v_count; 


13 


miScalar quantize(miScalar value, 


{ 


miScalar q = (miScalar) count; 


if (count < 2) 
return q; 
else 


return (miScalar) ((int) (value * q) 


} 


miBoolean show_uv_steps ( 


miColor *result, miState *state, 


{ 


result->r 


miInteger count) 


/ 


struct show_uv_steps *params) 


quantize (state-stex list [0] .x, 


*mi_ eval integer (&params->u_count) ) ; 


result->g 


quantize (state->tex list[0].y, 


*mi_eval_ integer (&params->v_count) ) ; 


result->b 0; 
return miTRUE; 


Figure 9.10: Shader source of show_uv_steps (p.483) 
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Now in lines 18-19 we make the assignment directly to the red component and in the same 
manner in lines 20-21 to the green component. We’ve defined function quantize in this shader 
source file to simplify show_uv_steps since we quantize both the w and v components. In the 
early process of writing a shader, we may define functions like quantize. Later, when those 
functions are found to be more generally useful, they can be included in a library available to all 
shaders, like the miaux functions we began developing in Chapter 7. 


We probably won’t be using the coordinate display shaders in any of our final imagery, but they 
demonstrate how we can write shaders to help visualize the data that mental ray is using during the 
rendering process. They’re analogous to printing intermediate values during software debugging, 
but since we’ve got so much data to print, we make explanatory pictures instead. 


9.3 Using the texture coordinates for texture mapping 


The texture coordinate system defined for the surfaces of our objects gives us a way to refer to 
positions in a digital image. When we use a digital image in this way, we call it a texture map 
because we are mapping the colors of the image, based on their position, to the surface of an 
object. 


Prog 211, 3.4.5. Textures, To refer to positions in the texture map, we can use the same kind of texture coordinate system we 
sat nal used for surfaces, with [0,0] in the lower left corner. In the simplest case, as in Figure 9.11, colors 
in the square polygon are sampled from the corresponding position in the texture map. 
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Figure 9.11: A mapping from a texture map to a polygon 


For our first texture map image, we’ll use a diagram that will help us see how the image is being 
mapped to the surface. 
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Figure 9.12: A source image for texture mapping 


A wide variety of image file formats can be used as texture maps in mental ray. We can also use Prog 18, 1.12. Texture 

the imf_copy utility to convert a variety of digital image formats to the mental ray .map format, sd a ae Saat 
which improves the efficiency of sampling the pixel values of the image. We use a texture map by Rend 511, A.5. Image Copy: 
creating a texture shader, which defines the type of data the texture shader will provide (scalars imf_copy 


or colors, for example), and associating a name for use in the .mi file with a filename. This is a Prog 245, 3.9. Texture 


é Shad 

special type of shader which can’t be used on its own, but provides access to the data contained a 

in the texture image. 

For example, if the filename of the number diagram image in Figure 9.12 is “fourgrid.tif” we can 

define a texture shader “fourgrid” in the scene file like this: Prog 112, 2.7.3. Textures 


color texture "fourgrid" "fourgrid.tif" 


A texture shader defined in this way can be passed as an argument to a shader parameter that is 
defined to be of type color texture. For our first texture mapping shader, that will be its only 
parameter. 


declare shader 
color "texture uv_ simple" ( 


color texture "tex" ) 
end declare 


Figure 9.13: Shader declaration of texture_uv_simple (p.484) 


Rendering the same scene that we used for the show_uv and show_uv_steps shaders, we can see the 
relationship of the texture map to the texture coordinate system defined for the surfaces. 
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color texture "fourgrid" "fourgrid.titf” 


material "grid" 
"texture uv_simple" ( 
rex" "Courgrid” } 
end material 


Figure 9.14: Using a texture map to define surface color 


The texture_uv_simple shader in Figure 9.14 uses the previously defined fourgrid texture 
shader as the argument to the tex parameter. All the work in the shader is done by the library 
function mi_lookup_color_texture. 


struct texture uv simple { 
miTag tex; 


/ 


miBoolean texture _uv_simple( 
miColor *result, miState *state, struct texture uv_simple *paras) 
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mi_lookup_color_ texture ( 
result, state, *mi_eval_ tag(&paras->tex), &state->tex _list[0]); 


return miTRUE; 


Figure 9.15: Shader source of texture_uv_simple (p.484) 


Notice in line 2 that a texture shader parameter in C is defined to be of type miTag, which 
requires us to use the library function mi_eval_tag in line 9. The fourth argument to 
mi_lookup_color_texture is the texture coordinate in the map, which in this case uses the 
first texture space, or state->tex_list [0]. 


9.4 Manipulating the texture coordinates 


In shader texture_uv_simple, we used the texture coordinates in tex_list[0] without 

modification to derive the mapping from the texture map colors to surface positions. We can 

Rend 58, 4.2.1. Texture modify this mapping to allow for greater flexibility. Shader texture_uv defines four parameters 
i a that can change the position and scale of the texture on the surface. 
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declare shader 


color "Cexture uv" { 
eolor texture "tex", 
scalar "u_seale" -default 1, 


scalar "v_scale" default 1, 

scalar "u_offset" default 0, 

scalar "v_offset" default 0 ) 
end declare 


Figure 9.16: Shader declaration of texture_uv (p.484) 


The default parameters in texture_uv for the scaling and offset factors duplicate the mapping 
relationship in texture_uv_simple. 


color texture "fourgrid" “fourgrid.ti£" 


material "grid" 
"texture uv" ( 


"tex" “fourgria", 

"u_ scale" 2, 

"uy offset" .125 ) 
end material 


Figure 9.17: Using a texture map with an offset and scale to change its position on the object 


The scaling for the u direction is set to 2.0, with the v scaling set to the default value of 1.0. The 
change of relative texture map position in w puts the corner of the square in the middle of one of 
the numbered boxes. 


Rend 58, 4.2.1. Texture 
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1 struct texture uv { 
2 miTag tex; 
3 miScalar u_scale; 
= miScalar v_scale; 
5 miScalar u_offset; 
6 miScalar v_offset; 
7 }; 
8 
9 miBoolean texture_uv( 
10 miColor *result, miState *state, struct texture _uv *params) 
‘| 
2 miVector uv_coord = {0.0, 0.0, 0.0}; 
is miScalar u_scale = *mi_eval_ scalar (&params->u_scale) ; 
14 miScalar v_scale = *mi_eval_ scalar (&params->v_scale) ; 
LS miScalar u_offset = *mi_eval_ scalar (&params->u_offset) ; 
16 miScalar v_offset = *mi_eval_scalar(&params->v_offset) ; 
17 
18 uv_coord.x = fmod((state->tex_list[0].x * u_scale) + u_offset, 1.0); 
19 uv_coord.y = fmod((state-stex_list[0].y * v_scale) + v_offset, 1.0); 
20 
21 mi_lookup_color texture ( 
22 result, state, *mi_eval_ tag(&params->tex), &uv_coord) ; 
23 
24 return miTRUE; 
25 } 


Figure 9.18: Shader source of texture_uv (p.484) 


Four local miScalar variables are defined in lines 13-16 that evaluate the scaling and offset 
parameters. These variables are then used in lines 18-19 to modify the texture coordinates in the 
first texture space, state->tex_list [0]. The standard C math function fmod in that calculation 
keeps the modified texture coordinates within the range of 0.0 to 1.0. This use of local variables is 
a matter of style; the function calls to mi_eval_scalar could be made in the arguments to fmod, 
but for larger numbers of parameters, the use of local variables in this way can clarify the way in 
which they are used later in the shader function. 


This is a very simple shader in the way that the texture coordinates are manipulated. The standard 
mental ray shaders include texture projection shaders that provide a wide variety of texture space 
manipulations. For these shaders, the uv coordinates are defined as a vector parameter so that 
other shaders can specify a projection transformation in a shader graph. 


9.5 Defining texture maps that tile well 


Texture maps can be designed so that they can be used in flexible ways by texture mapping 
shaders. This isn’t strictly part of the shader programming process, but some thought to the 
design of the texture images can simplify the shader programming process. 


For example, the black line in Figure 9.19 is half as thick in the vertical and horizontal direction 
as it is in the diagonal sections. 


9.6 Multiple texture spaces 87 


Figure 9.19: Texture map source image, with edges designed for tiling 


By designing the texture in this way, the black lines in the image will be the same thickness 
throughout if it is repeated in the texture space. 


color texture "octatile" "octatile.tif" 


material "tile" 
"texture uv" ( 


"tex" "octatile", 
"™ scale" 4, 
"vy scale" 4 ) 

end material 


Figure 9.20: An even tiling based on the design of the texture map image 


9.6 Multiple texture spaces 


In the previous shaders, we’ve only been using the first texture coordinate space defined in 
the miState struct, state->tex_list[0]. A modeling application can assign different texture 
coordinate spaces to an object with the intention that different attributes of the rendering—color 
and opacity, for example—will be texture mapped in different ways. 


We found that it was a useful debugging technique to interpret the first texture coordinate 
space as color. We’ll write a shader in which we can choose which texture space we wish to 
visualize. 


declare shader 
color "vertex color" { 


integer “uy andex" default 0 } 
end declare 


Figure 9.21: Shader declaration of vertex_color (p.485) 


The index of the texture space is the parameter uv_index to shader vertex_color. 


Prog 142, 2.7.10.4. Texture 
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struct vertex color { 
miInteger uv_index; 


miBoolean vertex color ( 
miColor *result, miState *state, struct vertex color *params) 
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miInteger uv_index = *mi_eval_ integer (&params->uv_index) ; 


\o 


result->r state-stex_ list [uv_index] .x; 
result->g state->tex list [uv_index] .y; 
result->b = state->tex_list [uv_index] .z; 
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return miTRUE; 


ao 
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Figure 9.22: Shader source of vertex_color (p.485) 


We can now visualize the two different texture spaces defined for a single object. 


material "texture space 0" 
"vertex color" { 


texture 7.tif "uv_index" 0 ) 
vi end material 


material "texture space 1" 
ivertex color" ({ 
"uy index" 1, ) 
end material 


texture 7 uv _1.t1£ 


Figure 9.23: Selecting different texture spaces defined in the object 
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In the definition of an object, different types of data can be associated with each vertex. In the 
scene file fragment in Figure 9.24 that produced Figure 9.23, you can see the two texture values 
for each vertex defined by the t character followed by the index into the vertex list. 


object "square" 
visible 
group 
# Coordinate data for XYZ position: 
= 5 =“, © 
a =>. 
oD eee». 0 
=) as 
First set of texture coordinates 
(see "Textures, Motion, Derivatives" in documentation of miState) : 


2 
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econd set of texture coordinates: 
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Following integers are indices into previous list of triplets: 
"vy" is vertex coordinate 

"et" is tex list array element, starting at 0 


e polygon; now integers refer to "v" definitions: 
3 
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end group 
end object 
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Figure 9.24: Multiple texture spaces defined in vertices with multiple “t” attributes 


You will rarely create objects “by hand,” but it is useful in understanding problems with a scene 
generated by an application to be able to examine the object definitions in the scene file. (We will 
talk more about the structure of objects in Chapter 19.) 


9.7. Noise functions 


In texture mapping, we define a relationship between some numerical attribute of the surface and 
a position in an image. In procedural textures, surface attributes are arguments to functions that 
calculate some value procedurally. A popular set of functions in computer graphics implement 
Perlin noise first proposed by Ken Perlin [Perlin 85, Perlin 05] as an efficient way of generating 
the basis for patterns like those found in nature. The mental ray API library contains a suite 
of twelve functions that calculate Perlin noise in one, two and three dimensions, with either a 
Gaussian or uniform distribution. The gradient (the direction of greatest change) at a point can 
also be calculated. 


Prog 359, 3.26.8. Noise 
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mi_noise_Nd Gaussian 
minoise_Nd_grad Gaussian 
mi_unoise_Nd uniform 
mi_unoise_Nd_grad uniform 
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Figure 9.25: Noise functions in the API library, N € {1,2,3} 


The scale of the noise is controlled by the input arguments to the noise functions. In Figure 9.7, 
the coordinates of a point in space was multiplied by a scalar value to change the apparent scale 


of the noise. 


Figure 9.26: Different scales of noise using the API function mi_unoise_3d 


By adding up a series of noise function values at different scales, we can produce imagery that 
resemble structures the are produced by complex dynamic processes, like marble or clouds. 
Function miaux_summed_noise scales and accumulates the result of mi_unoise_3d. 


double miaux_summed_noise ( 
miVector *point, 


double summing weight, double octave _ scaling, int octave_count) 


int i: 
double noise value, 


noise sum = 0.0, noise scale = 1.0, maximum_noise_ sum 


miVector scaled _ point; 


miaux set_vector(&scaled point, point->x, point->y, point->z) ; 


for (i = 0; i < octave count; i++) { 
noise value = mi_unoise 3d(&scaled_ point) ; 
noise sum += noise value / noise scale; 
maximum noise sum += 1.0 / noise scale; 
noise scale *= summing weight; 
miaux_ scale vector(&scaled point, octave scaling) ; 


} 


return noise sum/maximum_noise sum; 


Figure 9.27: Function miaux_summed_noise 


The term “octave” in the arguments to miaux_summed_noise is typical in functions that use 
repeated calls to a noise function by analogy to music, in which an octave difference in two 
notes is the result of doubling the frequency. At each octave, the contribution of the noise 
function calculated in line 12 is lessened by noise_scale in line 13 before it is added to the 
accumulated value noise_sum. This contribution factor is itself scaled at each iteration of the 
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loop in line 15. Each octave of noise contributes less and less, which creates detail at multiple 
levels of scale. 


In miaux_summed_noise, the source code of utility functions miaux_set_vector (line 9) and 
miaux_scale_vector (line 16) hasn’t been included since the role of both functions should be 
clear from their names. Simple functions like these that haven’t been defined in the text can be 
found in Appendix B by looking at the “utility functions” entry in the Index. 


We'll use miaux_summed_noise in a shader. Here we can see for the first time the importance of 
good default values for parameters. When a shader with many parameters implements a complex 
procedure, good defaults can allow the user to get a sense of what the shader can do without an 
in-depth knowledge of how it works. 


declare shader 
color "summed_noise color" ( 
scalar "point scale". default 1, 
scalar "octave scaling” default 2, 
scalar "summing weight" default 2, 


integer "number of octaves" default 5, 
scalar "red_exponent" default 1, 
scalar "green exponent" default 1, 
scalar "blue exponent" default 1 ) 

end declare 


Figure 9.28: Shader declaration of summed_noise_color (p.486) 


The defaults for the octave and summing weight calculations produce the image in Figure 9.29. 
The color exponents shift the red, green and blue components separately to create color from the 
single summed noise value. The pattern appears to be continuous across the edges of the objects 
because we are using the coordinates of the object as the basis for the noise function. 


material "summed_noise" 
"summed _ noise color" ( 
"point scale" 10, 


‘red exponent" .5, 

"green exponent" 1, 

"blue, exponent" 2.) 
end material 


Figure 9.29: Using noise to create textures based on object coordinates 


In shader summed_noise_color we call function miaux_summed_noise in combination with the 
color exponent parameters to define the surface color. 
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struct summed_noise color { 
miScalar point scale; 
miScalar octave scaling; 
miScalar summing weight; 
miInteger number of octaves; 
miScalar red_exponent; 
miScalar green_exponent ; 
miScalar blue exponent ; 


bi 


miBoolean summed_noise color ( 
miColor *result, miState *state, struct summed_noise color *params) 
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miScalar noise sum; 

miScalar red_exponent = *mi_eval_scalar(&params->red_exponent) ; 
miScalar green_exponent = *mi_eval_ scalar (&params->green_ exponent) ; 
miScalar blue exponent = *mi_eval_ scalar (&params->blue_exponent) ; 
miVector object point; 

mi point to object(state, &object point, &state->point) ; 

mi vector mul(&object_ point, *mi_eval_scalar(&params->point_scale) ) ; 
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noise sum = 
miaux_summed_noise(&object_ point, 
*mi_eval_ scalar (&params->summing weight), 
*mi eval scalar (&params->octave_ scaling) , 
*mi_eval_ integer (&params->number of octaves) ) ; 
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result->r = 

red_exponent == 1 ? noise _ sum : pow(noise_sum, red exponent) ; 
result->g = 

green_exponent == 1 ? noise _sum : pow(noise sum, green _exponent) ; 
result->b = 

blue exponent == 1 ? noise sum : pow(noise_sum, blue exponent) ; 


DO NN WN 
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return miTRUE; 
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Figure 9.30: Shader source of summed_noise_color (p.486) 


The color exponents will be used twice in the creation of the final color, so they are evaluated in 
lines 15-17 and assigned to local variables. The three parameters used in miaux_summed_noise 
are only used in that function call in lines 23-26, so their evaluation can be done when they are 
used as arguments to the function. 


Rather than using a texture coordinate space value as input to miaux_summed_noise, in lines 19- 
20 we scale the current surface point based on the point_scale parameter. Using the point in 
the space of the object as input has the advantage of providing a continuous mapping of a three- 
dimensional function across the surface of the object. The pattern appears to be part of the 
material, as if it’s a substance with interior structure like marble, rather than a box covered with 
marble wallpaper. 


Chapter 10 


The color of edges 


To draw edges and create other non-photorealistic effects, mental ray provides four different 
shaders that work together to specify separate phases of contour rendering. In the previous 
chapters, all our shader functions used the same argument signature, with the rendering state and 
parameters from the scene as input to a single C function that calculated the result. The set of 
four contour shader types are the major exception in mental ray to this basic pattern. 


Figure 10.1: Scene rendered with shader front_bright and with contours 


All the previous shaders have calculated a single color value by sending a ray into the scene. The 
shader’s result is the color an imaginary observer would see if she looked into the scene in that 
direction. Contour shaders, on the other hand, consider samples two at a time and decide if a 
mark of some sort should be drawn based on those two samples. This decision-making process 
is very flexible; one of the contour shaders specifies the information that should be stored for 
every sample that will be used to decide if and how some mark should be drawn. In this chapter, 
we'll learn how the four shaders are written as well as how they are used in the scene file. 


Rend 261, 10. Contours 
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Figure 10.2: A schematic overview of the four contour shading phases 


10.1 The four contour shader types 


To create contour lines in an image, mental ray breaks the line generation process into four phases. 
A separate shader is called for each phase. In the base shaders distributed with mental ray, these 
Rend 588, E.1. Contour Store four shader types are called Store, Contrast, Material Contour and Output shaders. Each of these 


anaes four shaders answers a question in the process of creating contours: 
Rend 588, E.2. Contour 


Contrast Shaders 


ee ey 1. Store What data will be necessary when deciding if a contour should be drawn? 
, E.3. Materia 

Contour Shaders 2. Contrast Has enough data been collected to draw a contour? 

Rend 598, E.4. Contour 3. Contour How should the contour be drawn? 


Ouspais Biases 4. Output How should the contours be used in creating the output image? 


The work of each contour shader type can be relatively simple since the work of determining 
where and how contours should be drawn is divided among them. The first three shaders execute 
multiple times as data is collected based on sampling during rendering. Figure 10.3 shows the 
process of contour calculation and output. 


Sample 
scene 
Call material 
shader 
1. Store 
Save contour data 


3. Contour 
Set endpoint values 


Sampling 4. Output 
completed? Write image 


Figure 10.3: Order of execution and interaction of the four contour shaders 


The input and output data for each of the four shaders differs from the pattern we’ve seen in 
previous chapters. 
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. Store — We determine what the Store shader should save for consideration during contour 


calculations by defining a struct with fields for the information we’ll need. In the standard 
contour shaders, this is a struct of type miStdInfo, defined in mi_contourshader.h. In 
the examples below, we'll call this datum the “contour info struct.” Two instances of the 
contour info struct from neighboring points are then available in steps 2 and 3. The current 
miState and the color calculated by the material shader are also available for use here. 


. Contrast —The use of the term “contrast” is similar to the contrast option in the scene file— 


both determine how much sampling is required during rendering. This shader determines if 
the data in the two structs defined by the Store shader and passed to the Contrast shader as 
arguments are different enough to warrant the creation of a contour at this spatial position. 
For example, object intersections can be generated by saving the instance tag (as a field 
value of the contour info struct in the Store shader), and specifying that a contour should 
be drawn if the two instance tag values differ. 


. Contour — The way that the contour should be drawn is defined by setting the field values 


of the miContour_endpoint struct, defined by mental ray in shader.h. Like the Contrast 
shader, the Contour shader has access to two instances of the contour info struct. The 
Contour shader function can also have a parameter argument like a typical shader. These 
shader parameters can be set in the scene file in the same manner as we have seen with 
previous shaders. 


Output — Once all the contour data has been defined, the Output shader can determine how 
that data should be used. Three standard Output shaders are defined: contour output only, 
contours composited over the normally rendered image, and the generation of PostScript 


files. 


10.2. Location of the contour shaders in the scene file 


The four contour shaders are located in three different blocks in the scene file. Because the Store 
and Contrast shaders are based in the sampling procedures of the rendering process, they are 
specified at the global level in the options block. The Contour shader is defined for a given 
material, and is defined in that material using the contour statement. The Output shader is one 
of the output statements in the camera. 


In Figure 10.4, the camera that includes the Output shader is defined before the material that 
contains the Contour shader. This is a typical ordering of these components; the contour shaders 
are executed based on the block in which they are contained and are therefore not dependent 
upon the order in which they appear in the file. However, all four contour shaders must be 
specified in the scene to generate contours in the final output image. 
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options "opt" 
object space 
samples 0 3 


contour store "c_ store" () 


options 


contour contrast "c contrast" () 
2. Contrast 


end options 


camera "cam" 
output “eontour" "< output" 1[) 
focal a2 
aperture ce 
aspect LL. 2s2255 
resolution 400 300 
end camera 


Camera 


4. Output 


material 


material "outline" 
contour "c_ contour" ( "width" .2 ) 
end material 


Figure 10.4: Location of the contour shaders in the scene file 


This scene file fragment assumes that the four contour shaders have been declared earlier in the 
scene file. In the next four sections, we will define this basic set. 


10.3. The Store shader: defining and saving contour data 


In the shaders of previous chapters, we could examine the value of the rendering state by using 
the miState pointer passed to the shader as an argument. In contour shading, we decide what 
subset of rendering state we'd like to use, and save that data with the Store contour shader. The 
Store shader has access to the miState struct as well as the color calculated by the material shader, 
provided as input arguments. The Store shader defines a struct to contain the data it will save for 
later use in the contour shading process and defines the values for the fields of that struct. We 
also specify the size of that struct for reference by mental ray. 


contour info struct 


Store shader 


color struct size 


Figure 10.5: Store shader 


The struct we'll define for our Store shader will just contain the tag of the instance and the normal 
at the ray intersection point. This will be enough information to draw lines between polygons 
or where two objects intersect. 


struct contour_info { 
miTag instance; 
miVector normal; 


}; 


Figure 10.6: An example C struct for a Store shader 


10.3. The Store shader: defining and saving contour data 97 


The “result” of the Store shader is the struct defined by it, like Figure 10.6, that will contain 

the data used by the Contrast and Contour shaders. But this result value is a C struct; all the 

previous shaders have returned a simple C data type defined by mental ray, miColor. As we'll see 

in later chapters, we can return other simple types as well. But besides using predefined types, 

shaders can declare a struct as a result in the scene file with the keyword struct and a list of its 

fields enclosed in braces. We’ll use this contour_info struct as the result of a Store shader called 

c_store. Figure 10.7 shows how the C struct of Figure 10.6 is declared as the result of Store  Prog63, 2.1.1. Parameter 
shader c_store. Sue 


declare shader 


struct contour info { 
miTag instance; 


,|Struct { geometry "instance", 


vector "normal" } 
miVector normal; 


}; "e store” {) 
end declare 


Figure 10.7: Specifying a struct result type in C as the return value for a shader declaration in .mi syntax 


Notice that the struct item in the .mi shader declaration is in the same syntactic position as 
the type color in previous shaders. When you see a shader with a struct keyword after 
declare shader, you need to look past the closing brace to see the name of the shader. 


declare shader 
struct { geometry "instance", 
vector "normal" } 
‘es ptore":.() 
end declare 


Figure 10.8: Shader declaration of c_store (p.487) 


Since we will be using the contour_info struct in the next two shaders, it is convenient to define 
a separate header file containing it and define a new type with typedef, as in Figure 10.9. 


#ifndef _CONTOUR_INFO H_ 
#define CONTOUR INFO H_ 


#include "shader.h" 


typedef struct { 
miTag instance; 
miVector normal; 

} contour_info; 


#tendif 


Figure 10.9: File contour_info.h 


The arguments of the Store shader define the shader’s inputs and outputs, returning a value of 
miBoolean. 
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miBoolean c_store ( 
void *info pointer, 
int *into size, 
miState *state, 
miColor *color) 


contour _info *info = (contour_info*)info_ pointer; 


info->instance = state->instance; 
info->normal = state->normal; 
*info size = sizeof (contour_info) ; 


return miTRUE; 


Figure 10.10: Shader source of c_store (p.487) 


Since different Store shaders will have different types of structs, the argument for the pointer to 
the struct is declared to be a pointer to void in line 2. In line 7, then, the argument is cast to the 
struct defined for this set of contour shaders, contour_info. In lines 9 and 10 the two fields of 
the struct are assigned values based on the state. Line 11 sets the info_size output argument; 
you should always include this statement in the Store shader to define the size of your contour 
information struct to mental ray. 


10.4 The Contrast shader: determining the location of contours 


The Contrast shader examines two of the contour info structs containing the data assigned by 
the Store shader to determine if a contour should be drawn at the current point. The functions 
returns an miBoolean value of miTRUE if a contour should be drawn, or miFALSE if not, in which 
case sampling will continue. The word “contrast” is used with the same meaning as the contrast 
control in the options block, in which we also control the number of samples required to satisfy 
some quality constraint. 


contour info #1 


contour info #2 


Contrast shader TRUE/FALSE 


parameters 


Figure 10.11: Contrast shader 


We’ll define a Contrast shader that draws edges where two faces meet at an angle greater than a 
threshold we'll specify as the dot product of the faces’ normals. 
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declare shader 
i Contrast” 


scalar "dot_threshold" default 0.71, ) 
end declare 


Figure 10.12: Shader declaration of c_contrast (p.487) 


Edges will be drawn if the dot product of the normals is less than the dot_threshold parameter 
(the angle measure is greater). The default value for dot_threshold is 0.71, roughly 45°. By 
specifying the parameter as the dot product, we can avoid repeated calculation of the cosine of a 
constant in the Contrast shader. (A graphical interface of an application could request from the 
user a more intuitive degree measure, with the conversion to the cosine value performed by the 
application when it adds the Contrast shader to the scene.) 


Note that the Contrast shader doesn’t return a value in a “result” pointer like other shaders, 
but signals the completion or continuation of sampling through the function’s return value. The 
declaration of the shader therefore does not have a datatype keyword for the return value before 
the name of the shader, c_contrast. 


The Contrast shader function examines the contour info struct pointers passed to it as arguments 
to determine if a contour should be drawn. 


struct c contrast { 
miScalar dot_threshold; 


miBoolean c_contrast ( 
contour info *infol, 
contour_info *info2, 
Lt level, 
miState *state, 
struct c_ contrast *params 
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if (infol == NULL | | 
info2 == NULL | | 
infol->instance != info2->instance | | 
(mi_vector dot (&infol->normal, &info2->normal) < 
*mi_eval_ scalar (&params->dot_ threshold) ) ) 
return miTRUE; 

else 
return miFALSE; 
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Figure 10.13: Shader source of c_contrast (p.487) 


We want to draw edges where the angle between faces exceeds a threshold. However, one or both 
of the samples may come from rays which have not intersected an instance (for example, rays 
which leave the scene without striking any objects), so in the Contrast shader we check both of 
the contour_info pointers to see if they are NULL in lines 12 and 13 before we further compare 
the value of their two fields. In line 14 we check the instance tags so that contours can be drawn 
where faces from two different instances intersect. Finally, in lines 15 and 16, knowing that we 
are comparing samples from the same instance, we check the dot product of the normals to see if 
they satisfy the threshold parameter. The threshold parameter allows us to treat some edges as 


Prog 293, 3.22.4. Contour 
Shaders 


Prog 294, 3.22.4. Contour 
Shaders 


100 10 The color of edges 


the result of an approximation of a smooth surface while other edges, as in the edges of a cube, 
are considered to be part of the geometric structure that we want to depict. 


10.5 The Contour shader: defining the properties of contours 


If the Contrast shader decides that two samples should define the endpoints of a contour line, 
the Contour shader is then called with two contour info structs of those samples, as well as the 
current miState and an optional set of parameters. The Contour shader assigns values to its 
result, a struct of type miContour_endpoint. 


miContour endpoint 


point 


color 


contour info #1 


width 


Contour shader 


motion 


normal 


material 


label 


Figure 10.14: Contour shader 


The miContour_endpoint is defined by mental ray as part of its internal contour shading 
implementation in header file shader. h. 


typedef struct { 
miVector point; 
miColor color; 
float width; 


miVector motion; 
miVector normal; 
miTag material; 
int label; 

} miContour_ endpoint; 


Figure 10.15: C struct defined by mental ray in shader .h for specifying contour data 


Only the width and color fields are required to be specified and will be set to constant values in 
simple Contour shaders. 
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Field Assignment Description 

point Set by default Coordinates x and y are in screen space, z is in camera space 
color Required Color of contour; alpha is treated as opacity 

width Required Width of contour expressed as a percentage of image width 
motion Optional Motion vector 

normal Optional Normal vector 

material Optional Material tag 

label Optional Object label 


Figure 10.16: The fields of the result struct for the Contour shader, miContour_endpoint 


The Contour shader is defined in the material, so different object instances can have different 
Contour shaders. In our first example, c_contour, we’ll specify as parameters the color and 
width to be assigned to the fields of miContour_endpoint. The color parameter includes an 
alpha value of 1. The alpha component defines the opacity of the contour line, so that the default 
color for c_contour is opaque black. 


declare shader 
"ae contour" { 


color "color" default 00041, 
scalar "width" default 1 ) 
end declare 


Figure 10.17: Shader declaration of c_contour (p.488) 


This parameter list syntax for Contour shaders is the same as we’ve seen before. However, the 
declaration does not include a result type; the Contour shader always specifies its result in its 
first argument as type miContour_endpoint. 


The “result” of the c_contour shader function is the miContour_endpoint struct passed as the 
first argument. 


struct ¢ coutour { 
miColor color: 
miScalar width; 


rs 


miBoolean c_contour ( 
miContour endpoint *result, 
contour_info *INEO near, 
contour info *info far, 
miState *state, 
struct. c_ contour *params) 
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result->color *mi_ eval _color(&params->color) ; 
result->width = *mi_eval_ scalar (&params->width) ; 
return miTRUE; 


Figure 10.18: Shader source of c_contour (p.488) 


In this simple case, we are not using any of the information in the contour info structs 
info_near and info_far. More sophisticated Contour shaders could set the field values 
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of miContour_endpoint based on the information stored in the contour info struct argu- 
ments. 


10.6 The Output shader: writing the contour image 


The Output shader uses the data set by the Contour shader in the miContour_endpoint to 
generate the final output image. An Output shader has as input arguments the current miState 
and any parameters defined for it. 


Output shader 


Figure 10.19: Output shader 


Our Contour shader creates a PostScript file, with the filename supplied as the only parameter 
to the shader. 


declare shader 
"e Sutput® 


string "postscript filename" ) 
end declare 


Figure 10.20: Shader declaration of c_output (p.488) 


The postscript_filename parameter to c_output is our first use of a string parameter in a 
shader. Unlike the typical representation of strings in C, this string is not a pointer to an array of 
characters in memory but is a tag in the database created by the scene file, an identifier that can 
be shared across a network of processors. To acquire the C string data, we need to use the tag to 
access the corresponding element in the scene database. 


char* miaux_tag_to_string(miTag tag, char *default value) 


char *result = default value; 
if (tag != 0) 


result = (char*)mi_db access(tag) ; 
mi_db unpin(tag) ; 


return result; 


Figure 10.21: Function miaux_tag_to_string 


The basic structure of any Output shader for contours uses mi_get_contour_line to loop through 
the set of contour line segments. 
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struct c output { 
miTag postscript filename; 


bi 


miBoolean c_output ( 


{ 


miColor *result, miState *state, struct c_ output *params) 
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miContour endpoint pl; 
miContour endpoint p2; 


FILE* fp; 
char* postscript filename = 

miaux_tag to _string(*mi_eval_tag(&params->postscript filename), NULL) ; 
if (postscript filename == NULL) 

postscript filename = "contour _output.ps"; 


mi _progress("Writing contour PostScript data to file %s", 
postscript filename) ; 


fp = fopen(postscript filename, "w") ; 

Forintt (ip, “esl\n"}; 

fprintf£(fp, "%%%sBoundingBox: 0 0 %d %d\n", 
state->camera->x_resolution, state->camera->y resolution) ; 


while (mi_get_contour_line(&pl, &p2) ) 
fFprintf(fp, "%g tg moveto %g %g lineto stroke\n", 
DL. pOLNE sx; “pT peint.y, 
p2.point.x, p2.point.y); 


fprintf(fp, "showpage\n") ; 
fclose(fp); 


return miTRUE; 


Figure 10.22: Shader source of c_output (p.488) 


In lines 12-13 we first dereference the miTag parameter for the PostScript filename we’ll use for 
output. Utility function miaux_tag_to_string is defined to return NULL if the tag did not refer 
to a value in the scene database. We give the filename a default value in line 15 if that is the case 
as determined in line 14. 


The library function mi_get_contour_line returns miTRUE for each pair of contour endpoints as- 
signed to its arguments. When all pairs of endpoints have been processed, mi_get_contour_line 
returns miFALSE. The single-statement loop in lines 25-28 writes to the file opened in line 20 the 
PostScript operators required to draw a line between the contour endpoints. The point field of 
miContour_endpoint is defined in screen space for x and y. The size of the image in PostScript 
points is therefore equivalent to the resolution of the image as defined in the camera field of 
miState. We use the resolution data to set the bounding box comment in lines 22-23. 


After all endpoint pairs have been processed and mi_get_contour_line has returned miFalse, 
we write the PostScript instruction to display the current page in line 30 and close the file in 
line 31. Because the Output shader only executes once, the PostScript file can be safely opened, 
written and closed in a single shader. 
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10.7. Using the four contour shaders 


Figure 10.23 uses the four previous shaders to generate a PostScript file containing the contour 
information. The Store and Contrast shaders are defined in the options block, the Output 
shader in the camera object block, and the Contour shader in the material block referenced by 
the instances to be drawn with the contours it defines. 


options "opt" 
object space 
samples 0 3 
Gontour store."c store" () 
contour contrast "c_ contrast" () 
end options 


camera "cam" 
output "contour" "ec output" () 


focal 32 

aperture 33.3 

aspect 1.333 

resolution 400 300 
end camera 


material "outline" 
contour "c_ contour" ( "width" .2 ) 
end material 


Figure 10.23: PostScript file generated by four custom contour shaders 


10.8 Compositing contours with the color from the material shader 


We can composite the result color of the material shader with the lines calculated by our contour 
shaders. We include two output statements in the camera, one to create and composite the 
contours, and the other to output the image in the normal manner. The contour compositing 
output statement uses the standard mental ray shader contour_composite. We also define a 
material shader that is used in the composite. Here, we’ve added the front_bright shader to the 
material. 


10.8 Compositing contours with the color from the material shader 105 


options "opt" 
object space 
samples 0 3 
contour store "c_ store" () 
contour contrast "c_ contrast" () 
end options 


camera "cam" 
output "contour, rgba" 
"Contour composite" () 
GuLput "reba"- "tar" 
‘contours: 3.tit" 
focal 32 
aperture 33.3 
aspect 1.333 
resolution 400 300 
end camera 


material "outline" 

"Front bright" {) 

eontour ."c contour", { "width" ..4 7 
end material 


Figure 10.24: Compositing contours with the result of shader front_bright 


The material in which we include our contour shader can use any shaders to generate the initial 
color layer. In Figure 10.25 we look ahead to the chapter on lighting and add solid black shadows 
to create a strong graphical effect. 


options -"ont" 
object space 
samples 0 3 
contour ‘store "ce store” {) 
contour contrast "c_ contrast" () 
end options 


camera "cam" 
output "contour, rgba" 
"cContour_composite" () 
output "rgba" "tit" 
"contours 4.tif" 
focal 32 
aperture 33.3 
aspect 1.333 
resolution 400 300 
end camera 


material "outline" 


"lambert" ( 
"datfuse" 11 1, 
"ambient" .1 .1 .1, 
"lighte" [light instance") } 
contour "ec. contour" ( "width" .2 ) 
end material 


Figure 10.25: Compositing contours with the result of shader lambert with shadows 
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10.9 Displaying tessellation with contour shaders 


Any data in the miState argument to the shader can be stored and compared for consideration 
in the generation of contours. We can use contour shaders to get an idea of how mental ray 
uses approximations to control the way an object is converted to triangles to be rendered, or 
tessellated. 


These tessellated triangles are called primitives, since they are the fundamental geometric entities 
that are rendered. Each primitive in the scene has a unique serial number, or the primuitive’s 
index. Some of the information about the primitive that the current ray has intersected is not part 
of the state, but can be acquired with the use of the mi_query function. By specifying a query 
request code of miQ_PRI_INDEX, we can retrieve the primitive’s index of the triangle intersected 
by the current ray. (We'll look at mi_query in more detail in Chapter 11 when we use it to get 
information about light elements in the scene database.) 


Since the primitive’s index uniquely identifies a geometric primitive, we can use it to determine if 
a contour should be drawn. If the primitive’s index is different for the primitives struck by two 
rays, then this must be a boundary between two primitives. Drawing a contour wherever this 
occurs will therefore generate a line drawing of an object’s tessellation. 


For this contour drawing, we'll use the standard mental ray shader as we did in Figure 10.25 to 
composite our lines on the image produced by the material shader. We’ll put the remaining three 
declarations for the Store, Contrast, and Contour shaders ina single file. We'll also put the source 
code of those three shaders in a single file. This will simplify the inclusion of these three shaders 
in a scene as well as facilitate the maintenance of these shaders in the future. Grouping a set of 
shaders designed to work together ina single file is a typical way of organizing them. For contour 
shaders, this organization becomes even more important, since the Store, Contrast, and Contour 
shaders all necessarily share the struct that determines where contours are drawn. 


The declaration of the three shaders for tessellation edge drawing are grouped together. I’m using 
the convention here of the prefix “c_” (for contour) with “tessellate_” to indicate that the three 
shaders have been designed to work together. The declaration in Figure 10.26 is saved in a single 
file so that it can be inserted into the scene file with a single $include statement. 


declare shader 
struct { integer "prim index" } 
"c tessellate store" () 
end declare 


declare shader 
"Cc tessellate contrast" () 


end declare 


declare shader 
"c tessellate contour" ( 
color "color" default 0 0 0 1, 
scalar "width" default 1 ) 
end declare 


Figure 10.26: Shader declarations for tessellation contour shaders (p.490) 


To control the size of the triangles in the tessellation, we can define the way in which objects 
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are tessellated with an approximation statement in the options block. In Figure 10.27, the  Progs9, 2.7.1.3. Tessellation 
approximation method has been set to be view dependent so that any edge will not exceed aay 
20 pixels in length (the length 20 argument). The scene file also uses the standard mental *"°8'6)7-14. 
- . : pproximations 
ray contour compositing shader, contour_composite, to combine the image produced by the 
material shader with the contours. In this case, the material shader is simply one_color with an 
argument of white. 


options "opt" 
object space 
samples 0 2 
contour store 
"ce tessellate_ store" () 
contour contrast 
"Se Céssellate contrast" {) 
approximate fine view length 20 all 
end options 


camera "cam" 
output “contour, rgba" 
"contour composite" () 
output "aba" "c2t" 


"contours 5.tif" 
focal 32 
aperture 33.3 


gay 
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| as VaVAW 14 aspect 1.333 
Wa WV y AK, Ee \ eral / resolution 
AVA KAS ARS end eer anal 
CON SUSESLINA oct ueeet ines 


"one color" ( 
idotor™® 1 i i} 
contour 
"ce tessellate contour" ({ 
"WIath® .2 ] 
end material 


Figure 10.27: Defining contours to show the tessellation of object instances 


As we did with their declarations, we'll group the three shader functions for contour tessellation 


together. 
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/* Info struct */ 
typedef struct { 
int primitive_index; 


} c_tessellate info; 


/* Store shader */ 
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miBoolean c_tessellate_ store ( 
void *info pointer, 
int *info size, 
miState *state, 
miColor *color) 
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c_ tessellate info *info = (c_tessellate_info*) info pointer; 
int primitive index; 

mi_query(miQ PRI INDEX, state, 0, &primitive_index) ; 
info->primitive index = primitive index; 

*info size = sizeof(c_tessellate info); 

return miTRUE; 
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} 


/* Contrast shader */ 
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miBoolean c_tessellate_ contrast ( 
c tessellate info *infol, 
c tessellate info *info2, 
int level, 
miState *state, 
void *params) 
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if (infol == NULL || 
info2 == NULL | | 
infol->primitive_index != info2->primitive_index) 
return miTRUE; 
else 
return miFALSE; 
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} 


/* Contour shader */ 


W 
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struct c_tessellate contour { 
miColor color; 
miScalar width; 


ky 


miBoolean c_tessellate_ contour ( 
miContour_endpoint *result, 
¢ tessellate_info *info_near, 
c tessellate info *info far, 
miState *state, 
struct c_tessellate contour *params) 
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result-séolor *mi_eval_color(&params->color) ; 
result->width = *mi_eval_ scalar (&params->width) ; 
return miTRUE; 
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Figure 10.28: Three shader functions for contour generation from an object tessellation (p.490) 


The design of a set of contour shaders begins by determining what data will be required to 
create the desired effect. The c_tessellate_info struct defined in lines 3-5 has a single field 
for the index of the current primitive. In the Store shader, we use mi_query in line 17 to get the 
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primitive’s index. We then record it by assigning it to the primitive_index field of the struct in 
line 18. 


We want to draw an edge if the two samples come from different primitives. However, one or 
both of the samples may come from rays which have not intersected a primitive (for example, rays 
which leave the scene without striking any objects), so in the Contrast shader we need to both 
of the c_tessellate_info pointers to see if they are NULL before we further compare the value 
of their two fields. By including a Contour shader parameter for color in the parameter struct 
defined in lines 42-45, we can differentiate different object instances in a large scene. 


In Figure 10.29, we composite the contour drawing of Figure 10.27 with the result of material 
shader front_bright using the standard mental ray shader, contour_composite. 


options "opt" 
object space 
samples 0 2 
contour store 
"c tessellate store" () 
contour contrast 
"c tessellate_contrast" () 
approximate fine view length 20 all 
end options 


camera “cam" 
output "contour, rgba" 
"Contour composite" () 


output "rqgba" "tir" 
‘contours 6.ti£" 
focal 32 
aperture 33.3 
aspect 1.333 
resolution 400 300 
end camera 


material "outline" 
"front bright" () 
contour 
"e tessellate contour" { 
MWwiGtLh”™ .2 ) 
end material 


Figure 10.29: Combining the tessellation display with shader front_bright 


10.9.1 The barycentric coordinates of a triangle 


The c_tessellate_contour shader in the material draws contour lines at the edges of triangles. 

We can also determine our location within a triangle using the current sample’s barycentric Prog 209, 3.4.4. Intersection 
coordinates, stored as field bary in miState. Barycentric coordinates define the relative position 

in a triangle based on the area of the three subtriangles created by that point and the triangle’s 

vertices. 
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A+B+C=1.0 


a 
Figure 10.30: Barycentric coordinates as the ratio of areas of subtriangles 


The area of the three triangles A, B and C are defined to add up to 1.0. The barycentric coordinate 
of a vertex is the proportional area of the subtriangle formed by the opposite edge. Intuitively, the 
barycentric coordinates describe “how close” a point in the triangle is to a vertex. For example, 
as the interior point approaches a vertex, the size of the opposite subtriangle approaches the full 
area of the triangle itself, or a barycentric component of 1.0. 


Like our other analysis shaders for normals and texture coordinates, we can map the three 
components of the barycentric to the colors of a material shader. For flexibility, we’ll define a 
color to be associated with the three components of the barycentric coordinate. 


declare shader 
color "show_barycentric" 
color “a” default 1 
color "b" default 
eolor “e" setault 

end declare 


ad 
ss 


Figure 10.31: Shader declaration of show_barycentric (p.491) 


Since the components of the barycentric coordinate add up to 1.0, our shader will accumulate the 
three colors defined by the shader’s parameters after scaling them by the barycentric component 
using the auxiliary function, miaux_add_scaled_color. 


void miaux_add_ scaled _color(miColor *result, miColor *color, miScalar scale) 


result->r += color->r * scale; 


1 
2 
3 
+ result->g += color->sg * scale; 
5 result->b += color->b * scale; 
6 


Figure 10.32: Function miaux_add_scaled_color 


The result color argument is initialized to zero in all components, so the shader simply calls the 
auxiliary function three times. 
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struct show barycentric { 
miColor a; 
mLCoLoY 5b; 
nfoler c; 


ha 


miBoolean show _barycentric ( 
miColor *result, miState *state, struct show _barycentric *params ) 


1 
2 
3 
4 
5 
6 
ie 
8 


\O 


miaux_add_scaled_color(result, mi_eval_color(&params->a), state->bary[0])j; 
miaux_add_scaled_color(result, mi_eval_color(&params->b), state->bary[1])j; 
miaux_add_scaled_color(result, mi_eval_color(&params->c), state->bary[2])j; 
return miTRUE; 
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Figure 10.33: Shader source of show_barycentric (p.491) 


The color parameters a, b and c in lines 2—4 are scaled in lines 10-12 by the three components of 
the barycentric coordinate stored as a field in the miState structure, state->bary. 


options "opt" 
object space 
samples 0 2 
contour store 
"c tessellate store" () 
contour contrast 
"“o tessellate contrast" () 
approximate fine view length 20 all 
end options 


camera "cam" 
Gutput "conteur, xrgba" 
"GONtCOUr Gomposite™" ({) 


output “staqba™ "Ei£" 
‘Worcours..7 skif" 
focal 32 


aperture 33.3 

aspect 1.333 

resolution 400 300 
end camera 


material "outline" 
"show barycentric" () 
contour 
"c tessellate contour" ( 
"width" .2 ) 
end material 


Figure 10.34: Displaying tessellation with contours composited over barycentric coordinates as color 
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10.10 Including color in the determination of contour lines 


In several of the previous sections, the contour lines were combined with the result of the material 
shader. These lines were composited using the standard mental ray shader contour_composite 
attached to the camera. The color produced by the material shader can also be made available 
when we make decisions about drawing contour lines. This color can be useful in producing 
contour lines that provide additional information about the geometric structure of the surface. 
The graphic quality of solid colors also has a cartoon-like appearance, resulting in the nickname 
“toon shading” for some variations of this approach. This is just the beginning of a set of 
techniques typically called “non-photorealistic rendering.” 


10.10.1 Contour lines at edges 


We'll start with the object in Figure 10.35 rendered with the front_bright shader. 


material "front" 


"trent braght" () 
end material 


Figure 10.35: Shader front_bright with ambiguous geometric details 


Using the contour shaders from Section 10.8, we can draw contours that represent edges and 
silhouettes. 
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options "opt" 
object space 
samples 0 2 
contour store "c store" () 
contour contrast "c contrast" ({) 
end options 


camera "cam" 
output "contour, rgba" 
"contour_composite" () 
OUtpUs "xqba” "ELIE" “aontotrs 9.tir" 
focal 2.3 
aperture 1 
aspect 0.833333 
resolution 250 300 
environment 
"one color" ( 
“eolor"™ 11 1. } 
end camera 


material "contours" 
‘one eolor" [ 
"eoloOr® 1 1 
contour 
"G contour" 
"width" 
Seo ler 
end material 


Figure 10.36: Contour shading drawing silhouettes, object intersection and internal edges 


10.10.2 Contour lines at color boundaries 


To generate contour lines by using the color produced by the material shader, we’ll modify the 
continuous result of the front_bright shader into discrete bands. The new contour contrast 
shader will specity that contour lines should also be drawn at color boundaries. 


We used the function quantize in shader show_uv_steps on page 81. We'll promote it to be an 
official member of our miaux utility functions. 


miScalar miaux quantize(miScalar value, miInteger count) 


J 

2 { 

3 miScalar q = (miScalar) count; 

4 i= (count < 2) 

5 return qd; 

6 else 

7 return (miScalar) ((int) (value * q) / (q - 1)); 
8 


} 


Figure 10.37: Function miaux_quantize 


We’ll use this function in a slight modification to shader front_bright to replace the continuous 
shading value with discrete intensity values. We’ll call this shader front_bright_steps. 
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declare shader 
color "front bright steps" ( 


color "tint" default 11 1, 
integer "steps" default 3 ) 
end declare 


Figure 10.38: Shader declaration of front_bright_steps (p.492) 


The only change to shader front_bright we need to make is to quantize the value of 
state->dot_nd. 


struct front bright steps { 
miColor tint; 
miInteger steps; 


}; 


miBoolean front bright steps ( 
miColor *result, miState *state, struct front bright steps *params ) 
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miColor *tint = mi_eval_ color (&params->tint) ; 
miScalar scale = 
miaux_quantize(-state->dot_ nd, *mi_eval_ integer (&params->steps) ) ; 
result->r = tint->r * scale; 
result->g = tint->g * scale; 
result->b = tint->b * scale; 
result->a = 1.0; 
return miTRUE; 


Figure 10.39: Shader source of front_bright_steps (p.492) 


The steps parameter is used as an argument to miaux_quantize in line 11. Rendering with 
shader front_bright_steps produces bands of constant gray values. 
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material "front_bands" 
"Front bright steps" ( 


"Steps" 6 ) 
end material 


Figure 10.40: Quantization of shader front_bright to produce bands of constant gray values 


To compare colors from the material shader calculation between two samples in the contour 
shading process, we need to save the color for each sample in the Store shader and then use it 
in the comparison of two samples in the Contrast shader. As we did with the set of tessellation 
shaders, we'll consider the Store, Contrast and Contour shaders for “toon shading” effects as a 
single unit. 
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typedef struct { 
miTag instance; 
miVector normal; 
miColor color; 

} c_toon_info; 


miBoolean c_toon_store ( 
void *info pointer, int *info_ size, miState *state, miColor *color) 
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c toon_info *info = (c_toon_info*)info pointer; 
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info->instance = state->instance; 
info->normal = state->normal; 
info->color = *color; 

*info_ size = sizeof(c_toon_info) ; 
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return miTRUE; 


} 


struct c_toon_contrast { 
miScalar dot_threshold; 


miBoolean c_toon_contrast ( 
¢_toon_info *infol, c_toon_info *info2, int level, miState *state, 
struct c_toon_contrast *params ) 
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if (infol == NULL || 
info2 == NULL || 
infol->instance != info2->instance | | 
(mi_vector dot(&infol->normal, &info2->normal) < 
*mi_eval_scalar(&params->dot_threshold)) | | 
infol->color.r != info2->color.r | | 
infol->color.g != info2->color.g | | 
infol-scolor.b != info2->color.b) 
return miTRUE; 
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else 
return miFALSE; 


} 


struct c_toon_contour { 
miColor color; 
miScalar width; 
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miBoolean c_toon_contour ( 
miContour_endpoint *result, c_toon_info *info near, c_toon_info *info_far, 
miState *state, struct c_toon_contour *params ) 
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result->color *mi_eval_color(&params->color) ; 
result->width = *mi_eval_scalar(&params->width) ; 
return miTRUE; 
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Figure 10.41: The Store, Contrast, and Contour shaders for lines at color boundaries (p.493) 


The c_toon_info struct in lines 1-5 contains fields for the instance tag, the normal vector, and the 
color to be saved for each sample. The void* pointer argument in line 8 is cast to the appropriate 
type for the Store shader in line 10. The instance tag and normal vector are copied from the 
miState struct in the Store shader in lines 12-13. By convention, the color is passed to the Store 
shader as its fourth argument; it is copied to the color field of the c_toon_info struct in line 14. 
Setting the info_size argument is required for all Store shaders and uses the C operator sizeof 
in line 15. 
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The Contrast shader in lines 24-39 defines where contour lines should be drawn—returns 
miTRUE—for four different cases: 


1. Lines 28-29 — One of the two sample rays did not strike an object, indicating a silhouette 
with no other objects in the background. 


2. Line 30 —- The two samples rays struck different objects, indicating either an interior 
silhouette or the interpenetration of two different object instances. 


3. Lines 31-32 — The angle between the normal of the two surface positions struck by the 
sample rays exceeds the threshold defined by the dot_threshold field from the params 
struct defined as a function argument in line 26. 


4. Lines 33-35 — The two colors of the material shaders from the sample rays are different. 
This condition will create the contour lines at the color bands. 


Finally, the Contour shader in lines 50-52 that determines the final appearance of the contour 
lines simply sets the color and width values passed as an argument when c_toon_contour is used 
in the object’s material. 


Using these three shaders and the standard shader contour_composite for output, contour lines 
are drawn at color boundaries. 


options "opt" 
object space 
samples 0 2 
contour store "c_toon_store" () 
contour contrast "c_toon_contrast" () 
end options 


camera "cam" 
output “contour, rgba”" 
"Contour composite" () 
output "r¢gba" "tir" “centoure 11.tit" 
Foca! 2.3 
aperture 1 
aspect 0.833333 
resolution 250 300 
environment 
"one color" ( 
"color”™ 111 ) 
end camera 


material "front bright contours" 
"front bright steps" ( 
"Steps" 6 ) 
contour 
"eo Goon contour” | 
With: <3; 
"color" 0001 ) 
end material 


Figure 10.42: Combining shader front_bright_steps with contours at color boundaries 
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10.10.3. Converting illumination shading into regions of single color 


In the same way that we quantized the colors in front_bright, we can modify the illumination 
models that we’ll develop in the next few chapters to produce solid bands of color. In Chapter 12, 
we'll develop a set of shaders that take light into account in shading a surface. One of the shaders 
simulates a “diffuse” surface in which light reflects evenly in all directions. 


light "Light" 
‘pointe laghit™ { 
wlighe color" 
origin 20 80 60 
end light 


instance "light_inst" "light" end instance 


material "diffuse" 
"lambert" ( 
"“a€iffuse™ 1 .9 .55, 
"lights" ["light_inst"] ) 
end material 


Figure 10.43: A diffuse surface with a single light 


Jumping ahead, we’ll modify shader lambert from page 150, adding a parameter to define how 
we should divide the typical continuous shading of the Lambert model into discrete steps. 


declare shader 
eolor "lambert steps" { 
color "ambient" default 0 


0 
color "diffuse" default 1 1 
integer "steps" default 3, 
array light “lights” 4 
end declare 


Figure 10.44: Shader declaration of lambert_steps (p.494) 


We'll cover how the Lambert model works later—for now, notice the modification in Figure 10.45 
of dot_nd in line 29 with miaux_quantize. 
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struct lambert steps { 
miColor ambient; 
miColor diffuse; 
miInteger steps; 
int 1, Laegente 3 
int n light; 
miTag Light [1]; 


ONAN FWN HP 


by 


miBoolean lambert steps ( 
miColor *result, miState *state, struct lambert steps *params ) 


\O 


ee 
WNHO 


int 1, light_count, light_sample count; 
miColor sum, light color; 

miScalar dot_nl; 

miTag *light; 


miColor *diffuse = mi_eval_color(&params->diffuse) ; 
miInteger steps = *mi_eval_ integer (&params->steps) ; 
miaux light _array(&light, &light count, state, 
&params->1i light, &params->n_light, params->light) ; 
*result = *mi_eval_color(&params->ambient) ; 


14 
LS 
16 
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for (i = 0; i < light count; i++, light++) { 
miaux set channels(&sum, 0) ; 
light_sample_ count = 0; 
while (mi_sample light (&light color, NULL, &dot_nl, 
state, *light, &light sample count)) { 
dot_nl = miaux_quantize(dot_nl, steps); 
miaux_add diffuse component (&sum, dot_nl, diffuse, &light_color) ; 


WNHONNNNNNNDN NH 
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} 
if. (light sample count) 
miaux add _scaled color(result, &sum, 1.0/light sample count) ; 


} 


return miTRUE; 
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Figure 10.45: Shader source of lambert_steps (p.494) 


Using shader lambert_steps, we can produce the same banding effect we saw with the divisions 
we made in front_bright_steps. 
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light "light" 
Wpoine Light” { 
Nlighe ¢elor® 1 ii} 
origin 20 80 60 
end light 


instance "light _inst" "light" end instance 


material "diffuse steps" 
"lambert steps" ( 
"steps" 6, 
"ditftuse" 1.9 .55, 
"lights" ["light_inst"] ) 
end material 


Figure 10.46: A diffuse surface with a single light with color banding 


Now everything is in place to create contours that use both the object’s edges as well as color 
boundaries in the modified Lambert shader. The Store and Contour shaders are defined in the 
options block, the Output shader is attached to the camera, and the Contour shader is added to 
the material. 
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options "opt" 
object space 
samples 0 2 
contour store "c_toon_store" () 
contour contrast "c toon contrast" () 
end options 


camera “cam" 
output "contour, rgba" 
"contour _composite" () 
output "rgba”™ “tif” "contours 14.tif" 
focal 2.3 
aperture 1 
aspect 0.823333 
resolution 250 300 
environment 
"ene color” { 
"sotor” ti 1.3 
end camera 


Light “ieant” 
"point Light® “( 
Staght setor™ 1.1.4 +} 
origin 20 80 60 
end light 


instance "light inst" "light" end instance 


material "contour diffuse steps" 
"lambert steps" ( 
"Steps" 6, 
“a@iztuse" 1.2 .bS, 
“lagnite” ["Laigkhe ianee")] } 
contour 
"¢ toon contour” { 
"width" .3, 
Ne6leor™® 0 0 6 1 } 
end material 


Figure 10.47: Adding contours to the color banding of a diffuse surface 


We can add shadows to the image by using a different light shader (described in the next chapter). 
However, we can no longer see contour lines in the shadows. 
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eptions “opr” 
object space 
samples 0 2 
contour store "c_ toon_store" () 
contour contrast "c_toon_contrast" () 
end options 


camera "cam" 
output "contour, rgba" 
"Contour composite" () 
CuUEnuE "rgba" “Bit" "contours 15.tii" 
focal 2.3 
aperture 1 
aspect 0.835533 
resolution 250 300 
environment 
Yone coor: ( 
"color" 1 a 2) 
end camera 


Light. “Zaght" 
"point light shadow" ( 
Sizghtneeige 1 1:1} 
Origin 20 80 60 
end light 


instance "light inst" "light" end instance 


material "contour diffuse steps" 
"lambert steps" { 
"Steps" 6, 
"diffuse" 1 .9 .55, 
"lights" ["“Laght anee™) ) 
contour 


"@ toon contour” { 
"width" .3, 
feolor® 0 0 0 1 j 
end material 


Figure 10.48: Adding shadows to the contour rendering of a banded diffuse surface 


By brightening the color of the contours lines, specified in the c_toon_contour shader in 
the material, we can still see object edges in the shadows—not a realistic representation, but 


potentially useful for maintaining information about object structure despite the current lighting 
condition. 
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options "opt" 
object space 
samples 0 2 
contour. store “c_ toon. getore" () 
conteur contrast."c toon contrast" () 
end options 


camera "cam" 
output "contour, rgba" 
"Contour _ composite" () 
Ciceuc'rgce” "cit" “contours 16.tift" 
rocal Z.3 
aperture: i 
aspect... 0.833333 
resolution 250 300 
environment 
‘one galor"® 4 
TeGlene Ltt } 
end camera 


material “contour_diffuse steps" 
"lambert steps" ({ 
"steps" 6, 
"Astiuge" 1.2455, 
Mlighte” [tiggnact snet*) ) 
contour 


"eo bocn contour- { 
"width" .3;, 
hep iog’” .5-.45 .275 1 ) 
end material 


Figure 10.49: Revealing contour detail in shadows with a brighter line color 


Ironically, these “non-photorealistic” techniques have depended heavily on the hallmarks of 
photorealistic rendering—perspective, shading based on light, and shadows. In the next part of the 
book we'll see how we can use these techniques to create increasingly “realistic” imagery. 
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Figure 10.50: Three color bands with a midrange color for contour lines 


Part 3: Light 


Chapter 11 


Lights 


In the previous chapters, we specified the color of an instance with a shader in the instance’s 
material. We can think of a shader as having a contract, the requirements for the shader given its 
use in the scene file. We define shaders for our simulation of lights, too, and the contract for the Rend 10, 1.2.3. Light Sources 
light shader is to define the color that is produced by the light. Prog 258, 3.13. Light Shaders 


The mental ray simulation of a light in a scene is defined by the light scene element. Depending Rend 133, 5. Light and 
upon the shader and the statements in the light element, the light will appear to come from a point sane 
or be directed like a spotlight. Additional parameters in the light element specify the attributes 
required to increase the realistic behavior of the light, including a definition of an “energy” value. 
Prog 117, 2.7.5. Lights 


11.1 Light from a single point 


The simplest light we can define in mental ray is a point light, simulating light radiating equally Prog 135, 2.7.9. Polygonal 
in all directions from a single point in space. Our only control of a point light in the shader is the seeecae | 
light color, defined by the single input parameter to the point light shader. 


declare shader 
color "point light" ( 


goiex, "light. coler", default 1 1.1.) 
end declare 


Figure 11.1: Shader declaration of point_light (p.495) 


Notice that the shader declaration is the same as those we saw in previous chapters, even though 
the shader will be used in a very different way. The source code for our point light will also be 
familiar from the shaders of the previous chapters. It is also quite simple; the contract of the light 
shader only requires that it defines the color of the light. 


Rend 134, 5. Light and 
Shadow 


Prog 117, 2.7.5. Lights 
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struct point light { 
miCoLlor light color; 
7 


miBoolean point light ( 
miColor *result, miState *state, struct point light *params) 


*result = *mi_eval_color(&params->light_color) ; 
return miTRUE; 
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Figure 11.2: Shader source of point_light (p.495) 


The light shader is as simple as it could be—it just defines the result to be the value of the color 
parameter. This is exactly what shader one_color did. In fact, we could employ one_color as a 
light shader; as we’ll see, other parameters in the light block define the geometric properties of 
the light, like its position and direction. 


When a light shader is part of a scene, it is the shader in the material attached to the object 
instance that modifies the color of the surface based on its orientation in space. We haven’t 
defined a shader that includes lights as a parameter yet, so we'll jump ahead and take a shader 
from the next chapter, lambert, that includes a list of lights as one of its parameters. As we’ll see 
in that chapter, it is the lambert shader, not spot_light, that modifies the color of the surface 
based on its orientation with respect to the incoming light on that surface, the surface’s incident 


light. 


NL 
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Figure 11.3: A point light and a surface it illuminates 


To render the scene with the default light_color parameter value of white, we call the shader 
without arguments. In the light element, various light parameters can be added. These are 
defined as statements in the light block, and are not parameters of the shader, though the shader 
can access their values, as we’ll see in Section 11.3. For our point light, we only need to include 
the origin parameter, which positions the light in world space. 


11.1. Light from a single point 


light: "white light" 
WeOlne Lighe® .t) 
origin 2 2 5 
end light 


instance "light_instance" 
"white light" 
end instance 


material "yellow" 
"lambert" ( 
"GiFiuse" 1:1 .4, 
"lights" ["Lhaght instance" ] 


end material 


material "blue" 
"lambert" ( 
"aiffuse" .4..54 1; 
Wlights" ["light anestance"] 
end material 


material "red" 
"lambert" ( 
"diffuse" 1 .4 .4, 
"lights" ["light_instance"] 
end material 


Figure 11.4: Point light with default white color 
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) 


By modifying the color parameter for the light, we see more clearly that the resulting colors of 
our objects are the product of both the surface orientation and the diffuse parameter used by 


the lambert shader. 


1aght< "reg Light® 
Wooint Light” f 
light. color 
origin 2 2 5 
end light 


instance "light_instance" 
"red light" 
end instance 


material "yellow" 
"lambert" ( 
"diffuse" 11 .4, 


"lights" ["light instance"] 
end material 


material "blue" 
"lambert" ( 
"diffuse" .4 .4 1, 
"lights" [“*light. instance") 
end material 


material "red" 
"lambert" ( 
"diffuse" 1 .4 .4, 
Wlagnce” -["Light instance” | 
end material 


Figure 11.5: Point light using color parameter 


) 
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Since we see that the contract for the light shader is to just specify a color, we can use any shader 
that returns a color. Since our point light shader only used the color passed as a parameter, we 
can use the shader one_color from Chapter 5 just as easily: 


int "red liek 

"one color". - ( 
"ealor 1 

Origin 2-2 5 


end light 


instance "light instance" 
eeeq Jight" 
end instance 


Figure 11.6: Point light with one_color as the light shader 


We'll continue to use these yellow, blue and red materials for the rest of our scenes in this 


chapter, only changing the definition of the light shader and the light object. 


11.2 A point light with shadows 


Rend 139, 5.2. Raytraced The calculation of shadows as they are cast by objects and affect the value of the light color is 
es also part of the contract of the light shader. But how the shadows are implemented by mental 
Rend 148, 5.3. Fast Shadows : ° ; 
veil lieder lena ray—whether through ray tracing or shadow maps—is not something you need to be concerned 


about in the light shader. 


Our point light shader with a shadow will still take a single argument, the light color. 


declare shader 
color "point light shadow" ( 


color "light chien? detain Tal I. 
end declare 


Figure 11.7: Shader declaration of point_light_shadow (p.496) 


Prog 326, 3.26.2. RC The calculation of the shadow value is performed by the API function mi_trace_shadow, and is 
ila used to modify the ideal (non-shadowed) light color. 
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struct point light shadow { 
miColor light color; 


J 


miBoolean point light shadow ( 
miColor *result, miState *state, struct point light shadow *params) 


*result = *mi_eval_ color(&params->light_ color) ; 
return mi_trace shadow(result, state); 
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Figure 11.8: Shader source of point_light_shadow (p.496) 


In line 9, the non-shadowed light color is passed as the first argument to mi_trace_shadow, and 

the result of that function call is used as the return value of the shader. In our previous shaders, 

we've always returned the boolean value miTRUE. In this shader we see for the first time the 

possibility of a return value of miFALSE. If mi_trace_shadow determines that occluding objects 

block the light completely (the result of the modification of mi_trace_shadow is black) or if the 

object being lit does not permit shadows to be cast on it (the object has “shadow receiving” set to Prog 124, 2.7.8. Objects 
off), then the boolean value miFALSE is returned from the mi_trace_shadow, and therefore from 

the shader. This allows mental ray to avoid any unnecessary further calculations. 


light "white light" 
"point light shadow" () 
origin 225 

end light 


instance "light instance" 
"white light" 
end instance 


Figure 11.9: Point light with shadows 
11.3. Asimple spotlight 


For the point light, we only specified its position with the origin parameter: 


light "white _light" 
‘Hoine Jagat {) 


origin 225 
end light 


Figure 11.10: Point light with position defined by the origin parameter 


However, a spotlight also requires the definition of a cone angle and a light direction. 
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spotlight 


direction 


Figure 11.11: A spotlight with a given cone angle and light direction 


Rend 137, 5.1. Point,Spot, By adding the direction and spread parameters, we specify the cone of a directional spotlight 
seaieiiaanniia die in the light element. Our shader will use these values in addition to the shader parameters (like 


light_color) to define a spotlight. 


light "white spotlight" 
"snotligan 
Orlgine2 2s 


direction -.75 -1 -2.3 
spread .978 
end light 


Figure 11.12: Spotlight defined by the origin, direction, and spread parameters 


The origin, direction and spread parameters define the geometry of the spotlight. 


origin 


direction 


Figure 11.13: A spotlight labeled by the statements used in the light object 


The spread value is expressed as the cosine of the angle between the light direction and the edge 
of the cone, or half the cone angle. If both vectors are normalized (their lengths are equal to 
one), then the dot product of these two vectors is equal to the cosine of the angle between them. 
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We can visualize the dot product of two vectors by thinking of the projection of one vector on 
another. 


0° 10° 90° 
aoememamememeee TE eben: | _ SS] = | I 
1.000 0.985 0.707 0.174 0.000 -0.342 


Figure 11.14: Two normalized vectors, the angle between them, and their dot product 


From this diagram, you can see that as the angle between the two vectors becomes smaller, the 
dot product gets closer to 1.0. This means that a spotlight with an infinitely thin cone has a 
spread of 1.0. As the cone angle gets closer to a hemisphere (180°), the spread gets closer to 0.0 
(the cosine of 90°, half of 180°). In some cases, we may also want to know if the angle is greater 
than 90°—if a vector is outside the 180° hemisphere centered around another vector—and in this 
case we simply check to see if the dot product is negative. 


When a material shader (the lambert shader in our example) requests a color value from the light, Prog 258, 3.13. Light Shaders 
or samples the light, the light shader is called, with state->point set to the current point in the 

material shader and state->dir set to the direction of the light to that point. We can therefore 

determine our position relative to the spotlight’s direction and spread. 


spotlight 


direction 


current point in material shader camera 


Figure 11.15: Sampling a point inside the cone of the spotlight 


If the current sample point is outside of the spread, then the light shader will return miFALSE, in 
a manner similar to the case in which we are in complete shadow. 
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direction 


camera 


current point in material shader 


Figure 11.16: Sampling a point outside the cone of the spotlight 


11.3.1. Acquiring light parameter values from the scene database 


As we saw in Section 5.3, access to the scene database is provided through tags—rather than 

pointers—to allow mental ray to render on multiple processors. To access the light parameter 

values, like spread, we need the tag of the light object that has been instanced. We can acquire 

Prog 374, 3.26.12. Auxiliary this tag from the database with the function mi_query. Once we have that tag, we can use the 
titi mi_query again to get the various light parameter values. 


Elements in the scene database are accessed by mi_query with query request codes. Here are some 
of the frequently used request codes for lights: 


miQ_LIGHT_ORIGIN Light position 
miQ-LIGHT_DIRECTION Light direction 
miQ _LIGHT_SPREAD Outer cone angle of spot light 


miQ-LIGHT_EXPONENT Distance falloff exponent (the value of 7 in 1/r”) 


Figure 11.17: Frequently used query codes for lights 


The use of mi_query gives us access to the database constructed by the scene file. 


instance "light instance" 


"white spotlight" 


mi_query(miQ INST ITEM, state, |state->light instance|,|&light tag}) ; end Ang hance 


light "white spotlight" 
"Spotlight" () 
erigin 2 2 5 
direction -.75 -1 -2.3 
spread .978 
mi_query(miQ LIGHT DIRECTION, state, light tag, end light 


mi_query(miQ LIGHT ORIGIN, state, light tag, 


mi_query(miQ LIGHT SPREAD, state, 


Figure 11.18: Accessing the scene element database with mi_query 
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Figure 11.18 shows this two step process: given the light instance tag—available as a field of the 
state structure, state->light_instance—we can find the tag for the instanced light object by 
using the miQ_INST_ITEM query. The attributes of the light are defined in the light object. Using 
the light object tag, we can use mi_query to get those attribute values. Notice that Figure 11.18 
shows the instance element above the light element, though their order would be reversed 
in the scene file. Our access through mi_query to the scene database requires that we first 
get the instance tag in order to then acquire the tag of the object from which the instance was 
made. 


miQ LIGHT SPREAD 
(cosine of half the cone angle) 


miQ LIGHT ORIGIN 
state->org (in light shaders) 


miQ LIGHT DIRECTION --}}------- . 
state->dir<44e00 8. . 
state- >parent =SoOLg 


cecilia’ cimiat state->parent->dir 


Figure 11.19: State fields and query codes used in light shaders 


In this diagram, the camera is no longer pictured as the origin of the ray that has caused the light 
shader to be called. The ray that intersects an object with a shader in its material that samples the 
light may be the result of any number of previous reflections and transmissions. The parent state 
of the light ray describes the ray that caused the light shader to be called. The origin of that ray is 
the origin of the ray in the parent of the state in the light shader, or state->parent->org. 


We can simplify the way we access these database values by wrapping the mi_query call in an 
auxiliary function. As usual, we are less concerned with the slight overhead of a function call 
than we are with shaders that are easy for us to debug and for other programmers to read. 


miTag miaux_current_light_tag(miState *state) 


{ 


miTag light tag; 
mi query(miQ INST ITEM, state, state->light instance, &light_tag) ; 
réturn light tag; 


Figure 11.20: Function miaux_current_light_tag 


The spread is also acquired with a single mi_query call. 
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miScalar miaux_light_spread(miState *state, miTag light_tag) 


2 
2 { 

3 miScalar light spread; 

4 mi_query(miQ LIGHT SPREAD, state, light_tag, &light_ spread) ; 
5 return light spread; 

6 } 


Figure 11.21: Function miaux_light_spread 


To determine if we are inside the spotlight cone, we need to compare the light direction vector 
with the vector from the light to the current point being illuminated. For the cone angle, we 
know the spread value (the cosine of half of the cone angle); for comparison purposes we need 
the analogous “offset spread” value between the light direction and vector from the light to the 
current illuminated point. 


miScalar miaux_offset_spread_from_light(miState *state, miTag light_tag) 
miVector light direction, light to sample point; 


mi_query(miQ LIGHT DIRECTION, state, light tag, &light direction) ; 
mi_vector normalize(&light direction) ; 


mi_vector to _light(state, &light_to sample point, &state->dir) ; 
mi_vector normalize(&light_ to sample point) ; 


return mi_vector dot (&light_to_sample point, &light_ direction) ; 


Figure 11.22: Function miaux_offset_spread_from_light 


In line 5, we acquire the light direction vector. In line 8, we transform the state->dir vector 
to the coordinate system of the light, giving us a vector that points from the light to the point 
for which we are calculating the light value. By normalizing the vectors in lines 6 and 9, we can 
return the dot product in line 11 that we will compare with the spread value in our light shader 
in the next section. 


spotlight 


offset spread 
light direction --}}------- > 


light to sample point JJ" - 


sample point 


Figure 11.23: Vectors compared for the offset spread in function miaux_offset_spread_from_light 
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We now have the information we need from our light instance to define a spotlight. A number 
of other attributes of lights are available for use in light shaders from the scene database through 


calls to mi_query. Prog 377, 3.26.12. Auxiliary 
Functions 
miQ-LIGHT_ENERGY Energy for caustics and globillum 
miQ_LIGHT_GLOBAL_PHOTONS Number of globillum photons to store 
miQ-LIGHT_GLOBAL_PHOTONS_EMIT Number of globillum photons to emit 
miQ_LIGHT_CAUSTIC_PHOTONS Number of caustic photons to store 


miQ-LIGHT_CAUSTIC_PHOTONS_EMIT Number of caustic photons to emit 


miQ_LIGHT_AREA Type: 0O=none, 1=rectangle, 2=disc, 3=sphere 
miQ_LIGHT_AREA_R_EDGE_U U size of rectangular area light 
miQ_LIGHT_AREA_R_EDGE_V V size of rectangular area light 
miQ_LIGHT_AREA_D_NORMAL Normal vector of disc area light 
miQ_LIGHT_AREA_D_RADIUS Radius of disc area light 
miQ_LIGHT_AREA_S_RADIUS Radius of spherical area light 
miQ_LIGHT_AREA_C_RADIUS Radius of cylinder area light 
miQ-LIGHT_AREA_C_AXIS Axis of cylinder area light 
miQ_LIGHT_AREA_SAMPLES_U Number of samples in U direction 
miQ_LIGHT_AREA_SAMPLES_V Number of samples in V direction 
miQ_LIGHT_TYPE Type: O=point, 1=directional, 2=spot 
miQ_LIGHT_SHADER Tag of light shader 
miQ-LIGHT_EMITTER Tag of light photon emitter shader 
miQ_LIGHT_USE_SHADOWMAP Light has a shadow map 
miQ_LIGHT_LABEL Light label 

miQ_LIGHT_DATA User data block 


Figure 11.24: Query codes for lights 


11.3.2 Using light parameter values in the shader 


As we saw in the previous section, the light object defines the spotlight’s origin, direction and 
spread. The declaration of our spotlight shader therefore remains as simple as the shader for the 
point light. 


declare shader 
color "sgpotligne™ tf 


color "ligme golor" default 11 1, } 
end declare 


Figure 11.25: Shader declaration of spotlight (p.496) 


The shader function determines if the current point is within the cone of the spotlight. 
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struct spotlight { 
miColor light _color; 
ji? 


miBoolean spotlight ( 
miColor *result, miState *state, struct spotlight *params ) 


1 
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miTag light tag = miaux_current_light_tag(state) ; 


\O 


if (miaux_ offset spread from_light(state, light_tag) 
> miaux_ light spread(state, light _tag)) { 
*result = *mi_eval_color(&params->light_ color) ; 
return mi_trace shadow(result, state) ; 
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} 


else 
return miFALSE; 
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Figure 11.26: Shader source of spotlight (p.496) 


The light tag acquired in line 8 is used in the conditional in which we compare the “offset spread” 
(the spread value between the light direction and the vector from the light to the illuminated 
point) to the spread of the light cone. Since the spread is a function of the cosine of the angle, the 
nearer the offset spread is to 1.0 the nearer the vector is to the light direction itself. Therefore, if 
our offset spread is greater than the light spread (the conditional in lines 10-11), we are within 
the cone. The result value has been initialized to the input parameter color in line 12, so we 
can include shadowing to our spotlight shader simply by calling mi_trace_shadow in line 13 and 
returning its Boolean value as the return value of the shader (as we did in our point light). We do 
not need to set result to black if the point is outside of the cone of the spotlight; that condition 
is specified by returning miFALSE if we are outside the cone. The evaluation of the light_color 
parameter will not be necessary if we are outside the cone, so to avoid unnecessary calculations 
params->light_color is not evaluated until it is required in the body of the conditional at 
line 12. 


light "white spotlight" 
teapot lian” .() 
origin 2 2 5 
direction -.75 -1 -2.3 
spread .978 

end light 


instance "light instance" 
"white spotlight" 
end instance 


Figure 11.27: Spotlight with cone represented by the cosine value of 0.978 (the “spread”) 
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11.4 Aspotlight with a soft edge 


We can soften the edge of our spotlight by gradually changing the light color from its full value 
to black at the edge of the cone. To do this, we’ll define an “inner spread” that is defined with 
the same cosine function as the spread of the spotlight. We will map the transition from the inner 
spread to the spread of the spotlight to a transition of color from the light color to black. 


direction 


Figure 11.28: An inner cone of full intensity inside the full cone of the spotlight 


Our new inner spread parameter is not part of the light object definition, so we'll add it as another 
parameter to a spotlight shader we'll call soft_spotlight. 


declare shader 
color "soft spotlight" ( 


golor Slight. ooloxs™ default 1 1,2, 
scalar "inner spread" default 1 ) 
end declare 


Figure 11.29: Shader declaration of soft_spotlight (p.497) 


Now our spotlight shader can’t simply rely on whether or not the current point is inside the cone; 
it needs to determine where that point is with respect to the inner and outer spread values. 
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struct soft spotlight { 
miColor light. color; 
miScalar inner_spread; 


}y 


miBoolean soft spotlight ( 
miColor *result, miState *state, struct soft spotlight *params) 


miScalar inner spread, attenuation; 

miTag light tag = miaux_current light _tag(state) ; 

miScalar offset_spread = miaux_offset_spread_from_light(state, light_tag) ; 
miScalar light spread = miaux_light spread(state, light tag) ; 


if (offset_spread < light _spread) 
return miFALSE; 


*result = *mi_eval_ color (&params->light_ color) ; 
inner spread = *mi_eval_scalar(&params->inner_ spread) ; 


if (offset spread < inner spread) { 
attenuation = miaux_fit(offset_spread, inner_spread, light_spread, 0); 
miaux_scale_ color(result, attenuation) ; 


} 


return mi_trace_shadow(result, state) ; 


Figure 11.30: Shader source of soft_spotlight (p.497) 


For efficiency, the test to see if the current point is within the cone of the spotlight happens as 
early as possible in the shader. To perform that test, however, we need to determine the offset 
spread and the light spread (lines 11 and 12) which require the light tag (line 10). The conditional 
structure is inverted from our spotlight shader; we test and return miFALSE first if we’re outside 
the spotlight cone. 


In line 17 we set the result value to the input color—we know we’ll need it now. Within 
the inner spread value (inside the inner cone) the light color is the full value of the input color. 
However, if we are in the region between the inner spread and the outer spread—the conditional 
of line 20—then we use miaux_fit to determine an attenuation factor in line 21, scaling the value 
from 1.0 to 0.0 as we go from the inner cone to the outer cone. We then use this attenuation 
factor to modify the input color in line 22. 


Whether or not we needed to attenuate the value, we still want to modify the color value based 
on shadows in line 24. 
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light "white spotlight" 
"Sort. spoteliguit” of 
"inner spread" .982 ) 
origin 2 2 5 
direction -.75 -1 -2.3 


spread .965 
end light 


instance "light instance" 
"white spotlight" 
end instance 


Figure 11.31: Spotlight with linear transition from inner cone to outer cone 


11.5  Aspotlight with a better soft edge 
If we look at the rendering in Figure 11.31, we can see a hard edge where the spotlight begins to 


fade to black. For that transition, we used function miaux_fit, which defines a linear transition 
between two values: 


double miaux_ fit ( 
double v, double oldmin, double oldmax, double newmin, double newmax) 
{ 


} 


return newmin + ((v - oldmin) / (oldmax - oldmin)) * (newmax - newmin) ; 


Figure 11.32: Function miaux_fit 


We can smooth out that discontinuity by using a sinusoidal transition rather than a linear 
one. 


Linear transition Sinusoidal transition 


Figure 11.33: Linear and sinusoidal transitions between two values 


To map values to a sinusoidal transition, we'll use miaux_fit twice. First we'll put the original 
value into a range between -90° and 90° and take the sine of that value. (Since the C sine function 
sin expects angles measured in radians, we’ll use the equivalent radian value of M_PI_2 for 90° 
defined in math.h.) The result of the sine function gives us sinusoidal values between -1.0 and 
1.0, which we then remap to our desired range. 
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double miaux_sinusoid fit ( 


{ 


double v, double oldmin, double oldmax, double newmin, double newmax) 


return miaux_fit(sin(miaux_fit(v, oldmin, oldmax, -M_PI_2, M_PI _2)), 
Shy ‘dks 
newmin, newmax) ; 


Figure 11.34: Function miaux_sinusoid_fit 


Our spotlight shader with softer soft edges is called sinusoid_soft_spotlight. 


declare shader 
color "sinusoid soft spotlight" ( 
color “light color" default 11 1, 
scalar "inner spread" default 1 ) 
end declare 


Figure 11.35: Shader declaration of sinusoid_soft_spotlight (p.498) 


The only change from soft_spotlight is the use of miaux_sinusoid_fit in line 22. 


struct sinusoid soft spotlight { 
miColor light color; 
miScalar inner spread; 


ii 


miBoolean sinusoid soft spotlight ( 
miColor *result, miState *state, struct sinusoid soft spotlight *params) 
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miScalar inner spread, attenuation; 

miTag light _tag = miaux_current light tag(state) ; 

miScalar offset_spread = miaux_offset_spread_from_light(state, light_tag) ; 
miScalar light spread = miaux_light spread(state, light tag); 
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if (offset_spread < light _spread) 
return miFALSE; 


*result = *mi_eval_ color (&params->light_ color) ; 
inner spread = *mi_eval_scalar(&params->inner_ spread) ; 


if (offset spread < inner spread) { 
attenuation = 
miaux_ sinusoid fit(offset_ spread, inner spread, light spread, 0); 
miaux_scale color(result, attenuation) ; 
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} 


return mi_trace_shadow(result, state); 
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Figure 11.36: Shader source of sinusoid_soft_spotlight (p.498) 


The sinusoidal fitting function produces a smoother transition from the full brightness of the 
inner cone to the beginning of the outer cone area. 
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light "white spotlight" 
"Sinusoid soft spotlight" 
"inner spread" .982 ) 
Origin 2 2 5 
dameaction =-.75 =-1 =2.3 


spread .965 
end light 


instance "light instance" 
"white spotlight" 
end instance 


Figure 11.37: Spotlight with sinusoidal transition from inner cone to outer cone 


11.6 Soft shadows using area lights 


With the sinusoid_soft_spotlight shader, the edge of the spotlight is soft. But because the 

spotlight is still defined as an infinitely small point, the edges of our shadows are hard. We 

can create soft shadows with any light shader by including an area light command in our light Rend 143, 5.2.2. Soft Shadows 
definition. An area light defines a geometrical structure as the source of the light. Eee serene: 


We usually think of a light as sending rays from the light into the scene. Shadows occur when an 
object blocks one of these light rays. 


Point light 


Figure 11.38: From the light to the surface 


We can, however, think of this process in reverse. Points on a surface will be in shadow if there 
is an object between that position and the light. 
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Point light 


Figure 11.39: From the surface to the light 


Thinking about lights from the surface to the light in this way is helpful in understanding area 
lights. For an area light, different surface positions will be exposed to different fractional amounts 
of the surface area of a geometric shape defined for the light. The size of that exposed area will 
determine the brightness of the surface at that position. 


Area light Area light Area light 
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Figure 11.40: Amount of the area light visible to the surface from different positions 


Based on Figure 11.40, you can also see how small changes in shadow position result in small 
differences in the amount of the area light that is exposed. This relationship accounts for the soft 
shadow edges that are characteristic of area lights. 


Using the sphere statement in the light object, we’ll redefine the light in Figure 11.9 to be 
an area light. The shader is the same, and the only difference in the scene file is the sphere 
statement. 


light "white light" 
"point light shadow" () 
origin 2 2 5 
sphere .5 8 8 

end light 


instance "light instance" 
"white light" 
end instance 


Figure 11.41: Point light shader with sphere area light command in light definition 
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11.6.1 Area light primitives 


The light element in the scene file defines its area light properties with one of six different area 
light primitives. Four are geometric structures expressed by vector and length information: 
rectangle, disc, sphere, and cylinder. You can also define an arbitrary object for the light 
source shape with the object primitive. Finally, the user area light requires a custom light 
shader that determines sampling locations. The light primitive is placed at the origin defined in 
the light block, and further positioned in the space by the transform of the light instance. Area 
lights are defined by a uv coordinate space in their construction and sampling definition. 


Figure 11.6.1 lists the arguments for the six area light primitives. Brackets indicate that the 
enclosed arguments are optional. 


Primitive Arguments 


rectangle [edge-1 edge-2 sampling | 


disc [ normal-vector radius sampling | 
sphere [ radius sampling ] 

cylinder [axis radius sampling | 

user [ sampling | 

object object-instance [ sampling ] 


Figure 11.42: Area light commands for the six area light primitives 


As we'll see in the next chapter, we determine the light value from an area light by evaluating 
whether the current point is exposed to an array of positions on the area light’s geometric extent. 
An area light sampling description specifies how many positions are evaluated, or sampled. By 
default, the number of samples for both u and v is 3, with a resulting total of 9 samples for the 
light. As with many sampling-based calculations, the more samples we take, the more accurate 
will be our final result. 


The number of samples in u and v can be specified explicitly. If only one is given, that value is 
used for both u and v. 


u-samples v-samples 


To improve performance, area lights can specify lower sampling rates for reflections and 
refractions. The total number of reflections and refractions for which the reduced sampling 
should occur is given as the sampling descriptions third parameter, called level. 


u-samples v-samples level 


With just the evel argument, the u-samples and v-samples values are set to 2 if the ray depth is 
higher than level. These override values can also be specified explicitly as the fourth and fifth 
sampling arguments. 


u-samples v-samples level low-u-samples low-v-samples 


For example, to specify a 1-unit by 1-unit rectangle in the xz plane with 8 samples in uw and v, 
you would add this area light command to the light block: 


rectangle 100 001 88 


Prog 118, 2.7.5.1. Area Light 


Sources 
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To include the control of reflection and refraction levels in this example, you would add three 
parameters that follow the uv sample values. For example, to specify 4 samples for a combined 
reflection and refraction level greater than 2, you would use this area light command: 


rectangle 100 001 88 2 44 


11.6.2 Using area lights in spotlights 


Adding an area light command to a spotlight shader combines any softening of the spotlight 
edge performed by the shader with the area light’s softer effect. The direction of the spotlight 
is independent from the orientation of the area light, however. Figure 11.43 adds a sphere area 
light command to the spotlight of Figure 11.37. 


light "white_spotlight" 
"Sinusoid soft spotlight" ( 
Winner: spread" .982 ) 
origin 22 5 
direction -.75 -1 -2.3 


spread .965 


sphere .5 8 8 
end light 


instance "light instance" 
"white spotlight" 
end instance 


Figure 11.43: Spotlight shader with sphere area light command in light definition 


11.7. Modifying light intensity based on distance 


In all of the light shaders we’ve written so far, the intensity has remained constant no matter how 
far from the light the surface happened to be. In the physical world, light diminishes proportional 
to the square of the distance between the source of the light and the illuminated surface. For 
our light shader that supports intensity falloff, we'll generalize this exponential attenuation so 
that that any value can be used, not just a power of two. The exponent in the light block can 
be referenced in the shader using the mi_query function to modify the resulting light color as a 
function of distance based on state->dist. 


miScalar miaux_light exponent (miState *state, miTag light_tag) 
miScalar light exponent; 


return light exponent; 


1 
2 
2 
= mi_query(miQ LIGHT EXPONENT, state, light tag, &light_exponent) ; 
2 
6 


} 


Figure 11.44: Function miaux_light_exponent 


Since the exponential falloff is controlled by the exponent statement in the light block, the 
declaration of shader point_light_falloff is the same as point_light. 


11.7. Modifying light intensity based on distance 147 


declare shader 
color “point iiaght falletr™ { 


color "light color", default: 1 1 1)) 
end declare 


Figure 11.45: Shader declaration of point_light_falloff (p.499) 


Acquiring the value of the exponent statement in point_light_falloff requires two calls to 
mi_query. 


struct point light falloff { 
miColor light color; 
he 


miBoolean point light falloff ( 
miColor *result, miState *state, struct point light falloff *params) 
{ 
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miTag light; 
miScalar exponent ; 
*result = *mi_eval_ color (&params->light color) ; 
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mi _query(miQ INST ITEM, state, state->light instance, &light) ; 
mi query (miQ LIGHT EXPONENT, state, light, &exponent) ; 
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miaux scale color(result, 1.0 / pow(state->dist, exponent) ) ; 
return mi_trace shadow(result, state) ; 
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Figure 11.46: Shader source of point_light_falloff (p.499) 


As with shader point_light and point_light_shadow, we initialize the shader’s result pointer 
to the light_color parameter. To determine the exponent value with mi_query in line 13, we 
first need the light instance, also available with mi_query. In line 15, we use state->dist, the 
distance from the light to the surface that sampled the light, to calculate the light color scaling 
factor. 


lignt "faliore light" 
"point light falloff" ( 
Wlight. color" 323 3 } 
origin 1.1.8 1 
exponent 2 
end light 


instance "light instance" 
"Sallofit light" 
end instance 


Figure 11.47: Point light with an exponential falloff 2.0 


Compared to the previous shaders, the diminishing light intensity throughout the scene creates 
a subtly more naturalistic appearance. Notice the decrease of apparent light intensity along the 
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side of the cone as it approaches the bottom. The darker area in the back of the scene is due 
not only to the increasing angle between the surface normal and the incident light, but to the 
exponential falloff based on distance as well. 


11.8 Defining good default values for parameters 


For our soft-edged spotlights, we defined a default value for the inner spread of 1.0. This means 
that the spotlight begins its fade from the light color to black beginning at the light direction 
itself. If the user of this shader does not specify a value for the inner spread, there will still be 
a good representation of the most important aspect of the shader—the soft spotlight edge. The 
default value also provides a specification to anyone integrating your shader into a graphical 
interface. 


light "white spotlight" 
"sinusoid soft _spotlight" () 
origin 22 5 
direction -.75 -1 -2.3 
spread .965 

end light 


instance "light instance" 
"white spotlight" 
end instance 


Figure 11.48: Spotlight with sinusoidal transition and default inner spread value of 1.0 


It’s a good idea to include a default value in the shader declaration for all of the parameter types 
that allow them. This value should best demonstrate the role of that parameter in the shader. In 
applications that present a graphical interface for shader parameter selection, these default values 
are the responsibility of the interface, but in shader development the default values defined in the 
shader declaration are very helpful in documenting the intended use of the shader. 


Chapter 12 


Light on a surface 


In our discussion of light shaders in the last chapter, we used a simple material shader that took 
the light into account to define the color of the surface. In this chapter, we’ll use our light shader 
with a variety of material shaders that approximate the affect of diffuse and mirror-like reflections 
from a surface. 


12.1. Diffuse reflection: Lambert shading 


When light strikes a surface, its diffuse reflected intensity is dependent upon the orientation of 
the surface with respect to the light. 


Normal vector 


Light 


Figure 12.1: The angle between the surface normal and the incident light direction 


If we define the surface by its normal vector, then the cosine of the angle between that normal and 
the incoming light direction is a scaling factor with which we can modify the combined values 
of the surface and light colors to define a perfectly diffuse reflector. This relationship was first 
defined by Johann Heinrich Lambert in the eighteenth century, and is called “Lambert’s cosine 
law.” 


We’ll define an auxiliary function to express this relationship, miaux_add_diffuse_component. 


Rend 52, 4.1. Color and 
Illumination 

Prog 365, 3.26.10. Shading 
Models 
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void miaux_add_ diffuse component ( 
miColor *result, 
miScalar light_and_surface_cosine, 
miColor *diffuse, miColor *light_color) 


result->r += light and surface cosine * diffuse->r * light _color->r; 
result->g += light and surface cosine * diffuse->g * light _color->5g; 
result->b += light_and_surface cosine * diffuse->b * light _color->sb; 


Figure 12.2: Function miaux_add_diffuse_component 


Notice that we’re adding to the pre-existing color value in result with the += operator in 
lines 6-8. We'll see why we need to do this in the shader itself. 


Since we will want to use our shader with more than one light, we need to accumulate multiple 


color values. We’ll use the function we defined to show barycentric coordinates in Section 10.9.1, 
miaux_add_scaled_color. 


void miaux_add_scaled_ color(miColor *result, miColor *color, miScalar scale) 


{ 


result->r += color->r * scale; 
result->g += color->g * scale; 
result->b += color->b * scale; 


Figure 12.3: Function miaux_add_scaled_color 


Before we accumulate the color values, however, a function to set all the channels to zero would 
be handy. Even though miaux_set_channels executes a trivial operation, the code will be clearer 
if we avoid four repetitions of a possible long miColor variable name. 


void miaux_set_channels(miColor *c, miScalar new value) 


new_value; 


Figure 12.4: Function miaux_set_channels 
Rend 543, C.6, Illumination | With these auxiliary functions we’re ready to define our first light-based shader, lambert. 
declare shader 


color "lambert" {( 
color "ambient" default 0O 0 0, 


color "diffuse" default 1114, 
array light "lights" ) 
end declare 


Figure 12.5: Shader declaration of lambert (p.499) 


Lambert’s cosine law defines how light that strikes a surface directly, or its local illumination, 


Rend 133, 5. Light and depends upon the orientation of the surface. In our shader, we’ll also add a parameter to define 
Shadow 
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ambient light, a constant amount light that is present in the environment as a result of inter- 
object reflection. This has been the traditional way to approximate what can now be more 
accurately modeled with global illumination techniques. (We'll see how mental ray provides 


global illumination mechanisms in Chapter 16, “Light from other surfaces.”) Rend 178, 7.1. Photon 
Mapping vs. Final 
Our third parameter for the lambert shader is a parameter array of lights. Because mental Gatering 


ray rendering can be distributed over a number of different processors, we can’t count on the 
consistency of addresses in memory as we normally do in C programming. For arrays, our .mi Prog 230, 3.5. Shader 
scene file parameter is translated in C into three fields of the parameter struct: ac naitahichiaea ein 


1. The offset from the base address to the first element in the array. 
2. The number of elements in the array. 


3. The base address defined by a single element array. 


Fields in the parameter struct in the C source file 


Shader declaration in the scene file 


int index offset_to first light; 
array light "lights" pale number of lights; 


miTag light array[1]; 


Figure 12.6: Declaration of an array in the .mi file and the three associated C struct parameters 


In the parameter struct for the lambert shader, we define the three array fields after the ambient 
and diffuse colors to match the order of the .mi declaration. Lights are passed to shaders as data 
of type miTag, so the light array base address is of type miTag[1]. 


struct lambert { 
miColor ambient; 
miColor diffuse; 


int i Ligne 7 
int n light; 
miTag light [1]; 


Figure 12.7: Source code of struct lambert (p.499) 


Whenever we need an array of lights, we need to use these three parameters for the offset, count 
and base address. For our shader, however, we only need a pointer to the first light and a count 
for the number of lights, so we’ll define an auxiliary function to process the light parameters. 
This function is not as concerned with reducing the size of the code as it is in encapsulating an 
error-prone but frequently necessary shader idiom. 


152 12 Light ona surface 


void miaux_light array(miTag **lights, int *light_ count, miState *state, 


{ 


int *offset param, int *count_param, miTag *lights param) 


int array offset = *mi_eval_integer(offset_param) ; 
*light count = *mi_eval_ integer(count_ param) ; 
*lights = mi_eval_tag(lights_ param) + array offset; 


Figure 12.8: Function miaux_light_array 


In the scene file, an array parameter is a list of values separated by commas and surrounded by 
square brackets. A single elements still requires the use of the square brackets for the array type, 
as you can see in the lights parameter of of the lambert shader in Figure 12.9. 


material "yellow" 
"lambert" ( 
"diffuse" .8 .7 .4, 
Piigntcs”- ("light inset” ] 
end material 


material "blue" 
"lambert" ( 


"diffuse" .4 .4 1, 
nlighte"® ["light. inst"! 
end material 


material "red" 
"lambert" ( 
"diffuse" 1 .4 .4, 
Tiehee) ("laght met") 
end material 


Figure 12.9: Lambert shading 


The structure of the lambert shader is dominated by the ight loop and the way that light colors 
are acquired in the shader. 
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struct lambert { 
miColor ambient; 
miColor diffuse; 
int came ee | 3h oar 
int nN LAGne; 
miTag Ligne {77 >; 


Py 


miBoolean lambert ( 
miColor *result, miState *state, struct lambert *params ) 


OANA UFPWN EP 


Xe) 


a 
NP 


int i, light_count, light_sample_ count; 
miColor sum, light color; 

miScalar dot_nl; 

miTag *light; 
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miColor *diffuse = mi_eval_color(&params->diffuse) ; 
miaux_light_array(&light, &light count, state, 

&params->1i_ light, &params->n_light, params->light) ; 
*result = *mi_eval_color(&params->ambient) ; 


DONE EF 
OF OO WO @ 


for (i = 0; i < light count; i++, light++) { 
miaux_ set channels(&sum, 0) ; 
light sample count = 0; 
while (mi_sample_ light (&light_ color, NULL, &dot_nl, 
state, *light, &light_ sample count) ) 
miaux_add_diffuse component (&sum, dot_nl, diffuse, &light_ color) ; 
if (light _sample_count) 
miaux_add_scaled_color(result, &sum, 1.0/light sample count) ; 
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} 


return miTRUE; 
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Figure 12.10: Shader source of lambert (p.499) 


In line 19, the three C struct fields defined as parameters in lines 4-6 are provided as arguments 
to miaux_light_array. The light variable, of type miTag*, is a pointer to the beginning of an 
array of light_count lights, both set in line 18. 


In lines 22-30, we loop over all the lights in the light array by incrementing the light pointer 
light_count times. To acquire the value of a light, we call the library function mi_sample_light. 
The output arguments to mi_sample_light provide additional information about the light besides 
its color for use in the shader. 


Type Argument name Description 

miColor* const result Result value (output) 

miVector* const dir Direction toward light (optional output) 

float* const dot_nl Dot product of surface normal and light direction 
(optional output) 

miState* const state State structure 

const miTag light_inst Light instance tag 

int* const samples Number of times light was sampled (output) 


Figure 12.11: Arguments to the function mi_sample_light 


By using mi_sample_light, we don’t need to include a special case in our shaders for area lights. 


Prog 324, 3.26.2. RC 
Functions 


Rend 52, 4.1. Color and 
Illumination 


Rend 544, C.6. Illumination 


Prog 376, 3.26.12. Auxiliary 
Functions 
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Note that it returns a Boolean value when sampling is complete, used as the conditional in the 
while loop in lines 25-26. The result of sampling an individual light is accumulated in the color 
sum, initialized to zero in all its channels in line 23. The number of samples is passed back in the 
light_sample_count argument in line 26. If an area light parameters were defined in the light 
element in the scene file, those parameters define how many light samples should be taken. For 
lights without area parameters, only a single sample is acquired, so the while loop only executes 
once. However, we may not have successfully sampled the light at all—we may be in complete 
shadow—so in line 28 we check to see if there were any samples to avoid dividing by zero in 
line 29. The result color is initialized to the value of the ambient parameter in line 20, and 
accumulates the sampled values of each light in line 29. If there are no lights or if all lights are fully 
occluded by other objects, the result value will therefore default to the ambient value. 


12.2. Specular reflections 


Lambert’s cosine law assumes a perfectly diffuse reflector, with light reflected evenly in all 
directions. Beginning in the 1970s, computer graphics researchers developed a series of specular 
reflection models to address the view-dependent reflection of light. The mental ray library 
contains API functions that implement several of these models. We'll use these functions to 
develop a set of shaders that represent part of the historical progression of direct illumination 
research. 


For each of these shaders, a different calculation for the specular light contribution is added to 
the diffuse component defined by Lambert’s law. The structure of these shaders are all therefore 
very similar. (As we'll see in Chapter 14, for historical reasons the word “specular” here refers 
to the type of reflection we will describe in that chapter as “glossy.”) 


12.2.1. The Phong specular model 


The first well-known specular model, developed by Bui-Tuong Phong and published in a paper in 
1975 [Phong 75], defines the apparent shininess of the surface with a specular exponent parameter. 
To augment our lambert shader with a Phong-based specular component, we’ll add a specular 
color and exponent to the set of parameters for the lambert shader. We'll call this shader phong. 


declare shader 
color "phong" ( 
color "ambient" default 
color "diffuse" default 


color "Specular" default 

scalar "exponent" default 

array light “lights” } 
end declare 


Figure 12.12: Shader declaration of phong (p.500) 


The mental ray API library includes a set of functions to implement a variety of specular reflection 
models. We'll create a set of corresponding auxiliary functions to simplify the structure of 
our shaders that include a specular component. The first function uses the library function 
mi_phong specular, and is called miaux_add_phong_specular_component. 
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void miaux_ add phong specular component ( 
miColor *result, miState *state, miScalar exponent, 
miVector *direction toward light, 
miColor *specular, miColor *light_ color) 


miScalar specular amount = 


mi phong specular(exponent, state, direction toward light) ; 
if (specular amount > 0.0) { 

result-sr += specular amount * specular-sr * light color-sr; 

result->g += specular amount * specular->g * light color->g; 

result->sb += specular amount * specular->sb * light color-sb; 
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Figure 12.13: Function miaux_add_phong_specular_component 


Function mi_phong_specular uses fields from current state structure for the surface normal 
(available as state->normal) and the direction of the ray (state->dir). The other arguments, 
exponent and direction_toward_light, are provided by the shader, as we’ll see in a moment. 
The angle of the ray may be such that there won’t be any specular component—specular_amount 
will be zero—so for efficiency’s sake we check for that in line 8. In lines 9-11 we added the scaled 
specular color to the result parameter; this value will be initialized to the diffuse component in 
our shader. 


The specular color and exponent parameters used by this function will be defined as parameters 
to the shader and specified in the scene file. 


material "yellow" 
"phong on ( 
"diffuse" .8 .7 .4, 
"specular" .8 .8 .8, 
"exponent" 40, 
‘rignts” ("light inet”! 
end material 


material "blue" 
"phong " ( 
"diffuse" .4 .4 1, 


"specular" .8 .8 .8, 

"exponent" 40, 

‘lignte* ("light inet") 
end material 


material "red" 
" phong a 
‘sai tiase” 1.4 4.4; 
"specular" 
"exponent" 40, 
‘Ligntcs" ("light inst*] 
end material 


Figure 12.14: Phong shading 


The structure of the phong shader is very similar to the lambert shader. 
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struct phong { 
miColor ambient; 
miColor diffuse; 
miColor specular; 
miScalar exponent; 
int i: Ligne s 
int nm light; 
miTag light [1]; 
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miBoolean phong ( 
miColor *result, miState *state, struct phong *params ) 


int i, light_count, light _sample_ count; 
miColor sum, light color; 

miVector direction_toward_light; 
miScalar dot_nl; 

miTag *light; 


miColor *diffuse mi_eval_ color (&params->diffuse) ; 
miColor *specular = mi_eval_ color(&params->specular) ; 
miScalar exponent = *mi_eval_ scalar (&params->exponent) ; 
miaux light _array(&light, &light_count, state, 
&params->i light, &params->n_light, params->light) ; 
*result = *mi_eval_color(&params->ambient) ; 


for (i = 0; i < light count; i++, light++) { 
miaux_ set _channels(&sum, 0); 
light sample count = 0; 
while (mi_sample light (&light_ color, &direction_toward_light, &dot_nl, 
state, *light, &light sample count)) { 
miaux_add diffuse component (&sum, dot_nl, diffuse, &light_color) ; 
miaux_add_ phong specular component (&sum, state, exponent, 
&direction_toward_light, 
specular, &light color) ; 
if (light_sample_ count) 
miaux_add_ scaled color(result, &sum, 1.0/light_sample count) ; 


} 


return miTRUE; 


Figure 12.15: Shader source of phong (p.500) 


Just like the lambert shader, the phong shader declares variables, acquires parameter values, and 
then loops for each light, sampling it with mi_sample_light. It only differs in the addition of 
lines 37-39, the call to our auxiliary function that adds the specular calculation to the diffuse 
component from line 36 for that light in the loop. 


12.2.2. The Blinn specular model 


Rend 52, 4.1. Color and The Phong model simulates a shiny surface with a specular exponent. James Blinn published a 
leiaisation specular calculation in 1977 [Blinn 77] based on research done by Torrance and Sparrow in the 
1960s [Torrance 67]. Their research described rough surfaces as modeled by very small grooves 
created by microfacets. The specular calculation is a combination of the average slope of these 
microfacets that control reflection, and the index of refraction of the material that controls how 

much of the light is absorbed rather than reflected. 
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We'll call the shader that uses this specular model blinn. The average microfacet slope and the 
index of refraction are specified as parameters to the shader. 


declare shader 
color "blinn" { 


color "ambient" default 0 0O O, 
color "diffuse" default 1114, 
color "specular" default O 0 O, 


scalar "avg microfacet slope" default .2, 
scalar "index _of refraction" default 3, 
array light "lights" ) 

end declare 


Figure 12.16: Shader declaration of blinn (p.502) 


The mental ray API library function that implements the Blinn’s model is called mi_blinn_specular. 
Like mi_phong_specular, it returns a scalar value, so the structure of our auxiliary function will 
also be similar to our previous function for the Phong calculation. 


void miaux_add blinn_ specular_component ( 
miColor *result, miState *state, 
miScalar roughness, miScalar ior, 
miVector direction toward light, 
miColor *specular, miColor *light_ color) 


miScalar specular amount = 
mi_blinn specular(&state->dir, &direction_ toward light, 
&Sstate->normal, roughness, ior); 
if (specular amount > 0.0) { 
résult-sr += specular, amount *. specular-sr * laght._color-sr; 
result->g += specular_amount * specular->sg * light _color->5g; 
result->b += specular_amount * specular->b * light color->sb; 


material "yellow" 
‘plinn* . { 
"diffuse" . .7 .4, 
"specular" 2 2 2, 
‘avg microfacet. slope" .25, 
"index of refraction" 20, 
lights" {*liaght inet") ) 
end material 


Figure 12.18: Blinn shading 


Rend 52, 4.1. Color and 
Illumination 
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The structure of the blinn shader is very similar to the phong shader—we only need to acquire 
different parameters and call miaux_add_blinn_specular_component. 


struct blinn { 
miColor ambient; 
miColor diffuse; 
miColor specular; 
miScalar avg microfacet_ slope; 
miScalar index _of refraction; 
int i Jight; 
int m light; 
miTag light [1] ; 


pi 


miBoolean blinn ( 
miColor *result, miState *state, struct blinn *params ) 


i 
miScalar avg _microfacet_slope *mi_eval_ scalar (&params->avg_microfacet_slope) ; 
miScalar index_of refraction = *mi_eval_ scalar(&params->index_of refraction) ; 
ot 
miaux_add_blinn specular_component ( 
&sum, state, avg_microfacet_ slope, index_of refraction, 
direction toward light, specular, &light_color) ; 


Figure 12.19: Shader source of blinn (p.502) compared to phong 


In the blinn shader, lines 15-22, lines 25-34 all lines after line 38 are identical to the phong 
shader. For the other typical specular models, we won’t need to vary the shader structure from 
the original structure we established in the phong shader. 


12.2.3. The Cook-Torrance specular model 


Cook and Torrance published research in 1981 [Cook 81] which added a color shift in the 
specular highlight based on the properties of real materials. The parameters for our shader 
that implements this model, cook_torrance, are identical to those of the blinn model with the 
exception of the index of refraction, which is a color, rather than a scalar value. This approximates 
the spectral differences in reflection based on angle, resulting in a change in color at the edges of 


highlights. 


declare shader 
color "cook _torrance" ( 
color "ambient" default 
color "diffuse" default 


color "specular® default 
scalar "average _microfacet_ slope" default 
color "index of refraction" default 
array light “lights” )} 

end declare 


Figure 12.20: Shader declaration of cook_torrance (p.503) 


Our auxiliary function also needs to take into account that the index of refraction is a color. 
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void miaux_add_cook_torrance_ specular component ( 
miColor *result, miState *state, 
miScalar roughness, miColor *ior, 
miVector direction toward light, 
miColor *specular, miColor *light_color) 


miColor specular reflection_color; 
if (mi_cooktorr_ specular(&specular reflection color, &state->dir, 
&direction toward light, 
&Sstate->normal, roughness, ior) ) { 
result-sr += specular reflection_color.r * specular->r * light color->r; 
result->g += specular reflection _color.g * specular->g * light color->sq; 
result-sb +=‘specular reflection: color.b * specular->b * light..color->b; 
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Figure 12.21: Function miaux_add_cook_torrance_specular_component 


Notice in the material that three numbers are specified as the color argument for the index of 
refraction in the shader. You can see the result in the difference in hue for the specular highlights, 
in particular in the blue sphere. 


material "yellow" 
"cook) torrance® 
"diffuse" .8 .7 .4, 
"specular" 2.2 2, 
"index of refraction" 10 5 80, 
‘tients ~[Sagkht -inet™] } 
end material 


Figure 12.22: Cook-Torrance shading 


The structure of cook_torrance is also very similar to phong. 
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Rend 104, 4.6. Anisotropic 
Shading 


Rend 52, 4.1. Color and 
Illumination 
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struct cook _torrance { 
miColor ambient; 
miColor diffuse; 
miColor specular; 
miScalar avg_microfacet_slope; 
miColor index of refraction; 
int i Light; 
int n laght; 
miTag light [1] ; 


ky 


miBoolean cook _torrance ( 
miColor *result, miState *state, struct cook_torrance *params ) 


a 
miScalar avg_microfacet_ slope *mi_eval_ scalar (&params->avg_microfacet_slope) ; 
miColor *index of refraction mi eval color (&params->index_of refraction) ; 
a 
miaux_add_ cook _torrance_ specular component ( 
&sum, state, avg _microfacet_ slope, index_of refraction, 
direction toward light, specular, &light_color) ; 


Figure 12.23: Shader source of cook_torrance (p.503) compared to phong 


Now that we have established a general structure for the addition of the diffuse and specular 
components for a direct illumination shader, we can substitute other types of specular calculations 
quite easily. 


12.2.4 The Ward specular model 


In the previous specular models, the position of the specular component has been dependent on 
our viewing angle. However, the shape of that highlight hasn’t been affected by the orientation 
of the surface. We say that such behavior is isotropic since it is the same in any direction. Greg 
Ward published a model for anisotropic reflection in 1992 to handle more complex reflections 
which are directional over the surface of an object. An example of such a material is brushed 
aluminum, in which bright lights create streaks across the surface. 


Surface direction in our shader will be defined by the texture coordinate space. We will specify 
the degree to which the surface reflects in the u and v directions by coefficients defined as shader 
parameters. 


declare shader 
color "ward" ( 
color "ambient" default 
color "diffuse" default 


color "glossy" default 
scalar "shiny _u_coeff" default 
scalar "shiny v_coeff" default 
array light "lights" ) 

end declare 


Figure 12.24: Shader declaration of ward (p.504) 


By specifying a higher coefficient in the u direction, we get highlights that streak vertically—they 
are narrower in u. 
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material "yellow" 
"ward" ( 
"diffuse" .8 .7 .4, 
"glossy" 22 2, 


"ashing: wm coert".1, 

"shiny v_coeff" 4, 

Mlagnie” ("light anet"™] 
end material 


Figure 12.25: Ward shading 


We divide our auxiliary function miaux_add_ward_specular_component into two parts to 
determine the specular component based on whether or not it is anisotropic, that is, whether 
or not the w and v coefficients are equal. 


void miaux_add_ward_specular_ component ( 
miColor *result, miState *state, 
miScalar shiny_u, miScalar shiny v, 
miColor *glossy, miScalar normal dot light, 
miVector direction toward light, 
miCcolor *light color) 


miScalar specular _reflection_amount; 
if ishiny’ wu == shiny v) °/* Isotropic */ 
specular reflection_amount = normal _dot_light * 
mi_ward glossy ( 


&state->dir, &direction toward light, &state->normal, shiny _u)j; 


else { /* Anisotropic */ 

miVector u = state-sderivs[0], v; 

float d = mi_vector dot(&u, &state->normal) ; 
state->normal.x; 
state->normal.y; 
state->normal.z; 

mi vector normalize (&u) ; 

/* Set v to be perpendicular to u (in the tangent plane) */ 

mi vector prod(&v, &state->normal, &u) ; 

specular reflection_amount = normal _dot_light * 

mi_ward_anisglossy(&state->sdir, &direction_toward_light, 
&Sstate->normal, &u, &v, shiny_u, shiny _v) ; 


(specular reflection amount > 0.0) { 

result->r += specular reflection amount * glossy->r * light _color->r; 
result->g += specular _reflection_amount * glossy->g * light_color->g; 
result->b += specular reflection amount * glossy->b * light _color->5b; 


Figure 12.26: Function miaux_add_ward_specular_component 


) 
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In lines 10-12 we handle the simple isotropic case by calling mi_ward_glossy. Because we are 
basing our anisotropy on the w and v directions, we need to calculate the tangent vectors for 
mi_ward_anisglossy in lines 15-22. For either case, we perform the same check for a non-zero 
specular component by examining specular_reflection_amount in line 27 and add the specular 
component to the incoming value of result in lines 28-30. 


struct ward 

miColor ambient; 
miColor diffuse; 
miColor glossy; 
miScalar shiny _u_ coeff; 
miScalar shiny v_coeff; 
int 1 light; 

int n light; 

miTag light [1] ; 
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miBoolean ward ( 
miColor *result, miState *state, struct ward *params ) 
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miColor *glossy mi eval color (&params->glossy) ; 
miScalar shiny _u_coeff *mi_eval_ scalar (&params->shiny_u_coeff) ; 
miScalar shiny v_coeff = *mi_eval_ scalar (&params->shiny v_coeff) ; 
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miaux_add_ward_specular_component ( 
&sum, state, shiny _u_coeff, shiny _v_coeff, glossy, dot_nl, 
direction_toward_ light, &light_color) ; 
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Figure 12.27: Shader source of ward (p.504) compared to phong 


We have isolated the complexity of the Ward model in our auxiliary function, so the ward shader 
has the same structure as before. 


12.3 Faking the specular component 


Given the structure for local illumination, we can define arbitrary specular calculations for 
non-realistic effects. The shader mock_specular allows for exaggerated color fringing around 


highlights. 


declare shader 
color "mock_specular" ( 
color "ambient" default 
color "diffuse" default 


color "specular" default 

coler “cyuceret™ default 

array light "lights" ) 
end declare 


Figure 12.28: Shader declaration of mock_specular (p.505) 


Here we add a non-physically based parameter cutoff to the parameters we have seen in the 
previous shaders. 
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void miaux_add_mock_ specular component ( 


i 

2 miColor *result, miState *state, 
3 miVector *direction_ toward light, 
+ miColor *specular color, 

5 micolor *cuboerr, 
6 

7 

8 


miColor *light color) 
{ 
miscalar lightdir offset, r_scale, g scale, b_sctale; 
9 miColor attenuated specular = {0,0,0,0}; 

10 
it lightdir offset = mi_vector_dot(&state->normal, direction _toward_ light) ; 
12 r scale = miaux_sinusoid fit _clamp(lightdir offset, cutoff->r, 1.0, 0, 
13 g scale = miaux_sinusoid fit_clamp(lightdir offset, cutoff->g, 1.0, 0, 
14 b scale = miaux_sinusoid fit_clamp(lightdir offset, cutoff->b, 1.0, 0, 
15 
16 miaux_scale channels (&attenuated_ specular, specular _color, 
17 r scale, g scale, b scale) ; 
18 miaux_multiply colors(light color, light color, &attenuated_ specular) ; 
18 miaux_add_color(result, light color) ; 
20 


Figure 12.29: Function miaux_add_mock_specular_component 


By scaling the red, green and blue components differently in lines 12-14, we can modify the color 
of the falloff of the highlight as it fades to the diffuse color. After the calculation of a highlight 
color, we add it to the result value as before in line 19 , with the same assumption as in our 
other shaders that the result input value will be the diffuse color. 


The colored fringes around the highlights that result are not based on any physical model, but 
derived from the different scaling values for the components. 


material "yellow" 
"mock specular" 
"diffuse" .8 
"Specular" .4 . : 
“Ombort”™ .6 «7 «8, 
"lights" (“light inst™] 
end material 


material "blue" 
"mock specular" ( 
"diffuse" .4 


"specuLar” <6. P 

"CUCGEL” «6 «sf By 

"“ligote™” ["laget inet”) 
end material 


material "red" 
"mock specular" { 
"diffuse" 1 .4 
"specular" 
MeucoLr™...5 
flagntce” ("light inet] 
end material 


Figure 12.30: A specular highlight model that ignores physics 


The mock_specular shader shows how custom specular calculations can fit in the structure we’ve 


established. 


) 
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struct mock specular { 
miColor ambient; 
miColor diffuse; 
miColor specular; 
miColor cutoft; 
int 1 Light ; 
int nH light; 
miTag light [1] ; 
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miBoolean mock specular ( 
miColor *result, miState *state, struct mock specular *params ) 
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miColor *cutoff = mi_eval_color(&params->cutoff) ; 
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miaux_add_mock_specular_component ( 
&sum, state, &direction_ toward light, 
specular, cutoff, &light_color) ; 


W W 
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Figure 12.31: Shader source of mock_specular (p.505) compared to phong 


12.4 Adding arbitrary effects to the Lambert model 


So far, we’ve been using the phong shader as a template for a series of other typical specular 
models. We can also use the lambert shader as a template for the basic light loop calculation in 
performs. For example, we’ll modify the diffuse calculation of lambert by adding a color value 
not dependent upon lighting direction, but on the orientation of the surface. 


declare shader 
color "rim_bright" ( 
color "ambient" default 
color "diffuse" default 
color-“2zim" default 
array E2ght "lignes ) 
end declare 


Figure 12.32: Shader declaration of rim_bright (p.507) 


Our auxiliary function is essentially the opposite of shader front_bright. 


void miaux_brighten rim(miColor *result, miState *state, 
miColor: *rim color) 


{ 
} 


miaux_add_ scaled color(result, rim_color, 1.0 + state->dot_nd) j; 


Figure 12.33: Function miaux_brighten_rim 


Since state->dot_nd is -1.0 when the normal is pointed toward us, and 0.0 at the edge (at 90°), 
the final argument in line 4 increases the amount of the rim_color value that is added as we get 
closer to the object silhouette. 
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material "yellow" 
Tih Seige” { 
"diffuse" .8 .7 .4, 
a gs 5 1 i, 
Wlights" ("light inst") 
end material 


material "blue" 
irim bright" { 
"diffuse" .4 .4 1, 


trim" eS 1 «S, 
"lighte" ["laght inet") 
end material 


material "red" 
"rim bright" ( 
"diffuse" 1 .4 .4, 
rim" 1 1 «SB, 
"lights" ["“light inst") 
end material 


Figure 12.34: Adding color to the rim of the object 


The different rim values create different colors based on the diffuse color. 


struct rim bright { 
miColor ambient; 
miColor diffuse; 
miColor rim; 
ink fi light; 
int n light; 
miTag light [1] ; 
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miBoolean rim_bright ( 
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miColor *result, miState *state, struct rim bright *params ) 
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miColor *rim = mi_eval_color(&params->rim) ; 
/* ... */ 
miaux brighten_rim(result, state, rim); 
return miTRUE; 


Figure 12.35: Shader source of rim_bright (p.507) compared to lambert 


The missing lines, lines 16-23 and lines 25-38, are identical to those parts of the lambert shader. 
The additional color added to the rim of the objects is done in line 39 after all other calculations 
have been completed, including the light loop. The lambert shader served as a basic template for 
the addition of an effect not based on illumination. 
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Chapter 13 


Shadows 


Chapter 11, Lights, introduced the idea of a shader contract that defines the requirements for 
shaders of a given type. For example, to include the attenuation of a light by shadowing for direct 
illumination, a light calls the library function mi_trace_shadow. 


struct point light shadow { 
miColor light eolor; 


/ 


miBoolean point light shadow ( 


miColor *result, miState *state, struct point light shadow *params) 


*result = *mi_eval_ color (&params->light color) ; 
return mi_trace_shadow(result, state) ; 
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Figure 13.1: Point light with shadowing provided by mi_trace_shadow (p.496) 


A light shader is called when it is sampled by mi_-sample_light, as in the lambert and other  Prog324, 3.26.2. RC 
direct illumination shaders. Functions 


* f 
while (mi_sample light (&light_ color, NULL, é&dot_nl, 
state, *light, &light_sample_ count) ) 


miaux_ add diffuse component (&sum, dot_nl, diffuse, &light_color) ; 
if (light _sample_count) 
miaux_ add_scaled_color(result, &sum, 1.0/light_sample_count) ; 


ats 


Figure 13.2: Function mi_sample_light in the context of the light loop in the lambert shader (p.499) 


When the light is sampled, any objects between state->point and the light that have been defined 
to cast shadows are examined. To calculate shadows, these occluding objects are considered in Rend 147, 5.2.3. Shadow 
an order based on the shadow sort order. Shadow shaders can be defined in the material of an oe poten 
instance, and these shaders are run during mi_sample_light. A shadow shader initially contains , 

; : : : ‘ , rog 264, 3.14. Shadow 
the current light value in the result pointer, and it modifies this light value based on how the Shaders 


object instance should cast shadows. The Boolean return value of a shadow shader indicates 
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whether any further shadow shaders should be called by returning miFALSE if the resulting red, 
green and blue components are all zero. 


If the material of an instance has not defined a shadow shader, then the instance is considered 
to be fully opaque, with the resulting light color components set to zero. The default behavior, 
handled internally by mental ray, is equivalent to the shader in Figure 13.3. Because all resulting 
color components are set to zero, the shader returns miFALSE in line 5. 


miBoolean shadow default ( 


{ 


miColor *result, miState *state, void *params ) 


1 
2 
3 
4 result->r = result->g = result->b 
5 return miFALSE; 

6 } 


Figure 13.3: Shader source of shadow_default (p.508) 


Shadow shaders are defined by the shadow statement in the material. 


material "transparent 75" 
"transparent" ( 
"color" = "tile shader", 
"Cransparency” .75 .75 .75 } 


shadow 


"shadow default" () 
end material 


Figure 13.4: Material description transparent_75 for cylinder on left 


Notice in Figure 13.4 that the effect of object transparency is separated from the nature of the 
shadows by the use of separate shaders. The following sections develop shaders that create 
shadows from transparent objects. Those shaders will modify the incoming light in the result 
pointer, and test the value of the final color component values to determine the Boolean status 
to return. In Section 13.5 we’ll also see how the material and shadow shaders can be combined 
into a single shader to simplify the specification of shared parameters between the two shader 


types. 


13.1 Color shadows without full transparency 


For a shadow shader for an instance, we need to specify at least a color and the transparency 
value. 


13.1 
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declare shader 
color "shadow _color" ( 


color "color" default 11 1, 
color "transparency" default .5 
end declare 


Figure 13.5: Shader declaration of shadow_color (p.508) 


Given that the contract of the shadow shader is to modify the input light value (saved in 
the result pointer), our first attempt will simply multiply the light value by the color and 
transparency. 


/* 
This is an incorrect calculation of the shadow color -- you can’t 
just multiply the original light color by the transparency and 
surface colors. 


a 


#include <shader.h> 
#include "miaux.h" 
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struct shadow color { 
miColor color; 
miColor transparency; 


hy 


miBoolean shadow color ( 


miColor *result, miState *state, struct shadow_color *params ) 


{ 


miColor *color = mi_eval_color(&params->color) ; 
miColor *transparency = mi_eval_ color(&params->transparency) ; 


result->r *= color->r transparency->1r; 
result-sg *= color->sg transparency->g; 


result->b *= color->b transparency->b; 


return miaux_all channels equal(result, 0.0) ? miFALSE : miTRUE; 


Figure 13.6: Shader source of shadow_color (p.508) 


We'll render three objects, with transparency values at 25%, 50%, and 75%. 


170 13 Shadows 


material "transparent 25" 
"transparent" ( 
"color" = "tile shader", 
"transparency" .25 .25 .25 ) 
shadow 
"shadow _color" ( 
"color" = "tile shader", 
"transparency" .25 .25 .25 ) 
end material 


material "transparent 50" 
"transparent" ( 
"color" = "tile shader", 
"transparency" .5 .5 .5 ) 


shadow 
"shadow _ color" ( 
"color" = "tile shader", 
"transparency" .&S .5 «5 ) 
end material 


material "transparent 75" 
"transparent" ( 
"color" = "tile shader", 
"transparency" .75-.75 .75 } 
shadow 
"shadow _color" ( 
"color" = "tile shader", 
"transparency" .75 .75 .75 ) 
end material 


Figure 13.7: Transparent shadows with apparent inconsistency in higher transparency values 


But the cylinder on the left uses the material shown in Figure 13.7 and its transparency parameter 
is 0.25—shouldn’t the shadow be fainter? How will we know if our shadow shader is calculating 
the correct value? 


We can render a simpler image with transparency values that change in even increments from 
0.0 to 1.0 to get a better sense of how variation in transparency changes the shadow color. 
In Figure 13.8, the twenty-one vertical strips are rendered with the transparent shader from 
Chapter 8 and vary in transparency from 0.0 to 1.0 in increments of 0.05. The strips in the lower 
part of the image are shadows. The material in Figure 13.8 is used by the tenth strip from the left 
with a transparency value of 0.45. 


material "shadow _transparent_45" 
"transparent" ( 
"aolor" — heraa" , 
"transparency" 0.45 0.45 0.45 ) 


eae | shadow 
"shadow_color" ( 
"csolor"® = "grid", 
"transparency" 0.45 0.45 0.45 ) 


end material 
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Figure 13.8: Creating an incremental ramp of transparency values to determine the accuracy of a shader 
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The problem with shader shadow_color is obvious now: the shadow should be invisible at the 
full transparency value at the right of Figure 13.8. We can also visualize the scaling factor that 
will be applied to the light color by creating a graph of one component (red, green, or blue) of 
the color and transparency. We'll plot a set of shadow color component values (0.0, 0.1, 0.2, ... 
1.0) multiplied by a set of shadow transparency values. The resulting graph shows the way that 
color and transparency combine to create the fraction by which the shadow shader will scale the 


light. 
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Figure 13.9: Product of the shadow color and shadow transparency 


At full transparency, all the resulting scaling values for the light should be 1.0, that is, there will 
be no change to the light value because the object is completely transparent and does not cast a 
shadow. By the graph, we can see that at a transparency value of 1.0 (full transparency), our naive 
multiplication of transparency and the input color results in the input color itself. 


Creating test scenes with a consistently varying parameter values is similar to the practice of 
wedging color correction values in film production. We’ll use a combination of parameter wedg- 
ing and plots of transparency values to help test better implementations of shadow transparency. 
To simplify our shadow shaders, we’ll assume that autovolume mode is enabled in the case of 
shadowed volumes. This allows us to ignore the maintenance of state->refraction_volume as 
demonstrated in the mental ray base shader mib_shadow_transparency. 


13.2. Midrange transparency control 


At a transparency value of 0.0, the object is opaque and the shadow is therefore black. At 
transparency 1.0 the shadow is no longer visible. All color components therefore need to be 
scaled to 0.0 at a transparency value of 0.0 and all scaled to 1.0 when transparency is 1.0. This will 
require that midrange values be handled differently for the various color component values. In 
the simplest case, we can simply pick an arbitrary point in the transparency range and “expand” 
the component values to the full range at that point, and then contract so the result is 1.0 for 
transparency 1.0 for all component values. 
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172 13. Shadows 


1.0 


Shadow color 


ae Shadow transparency 


Figure 13.10: Light attenuation with transition at breakpoint 


The function that implements this set of values defines a “breakpoint” as an argument. 


double miaux_shadow breakpoint ( 
double color, double transparency, double breakpoint ) 
{ 


if (transparency < breakpoint) 

return miaux fit(transparency, 0, breakpoint, 0, color); 
else 

return miaux_fit(transparency, breakpoint, 1, color, 1); 


Figure 13.11: Function miaux_shadow_breakpoint 


The function divides the transparency values into two parts. For any value less than the 
breakpoint, line 5 rescales the range of /0, breakpoint] to [0, color]. The second range, 
[breakpoint, 1], is rescaled to [color, 1] in line 7. Intuitively, the component values start at 


0.0 and ramp linearly to the input color values at the breakpoint, and ramp from the breakpoint 
ter hD. 


Shader shadow_breakpoint includes the breakpoint as a parameter. 
declare shader 


color "shadow breakpoint" ( 
eolor "color" default 1 1 i, 


color "transparency" default 
scalar "breakpoint" default 
end declare 


Figure 13.12: Shader declaration of shadow_breakpoint (p.509) 


The shader scales the value of the red, green and blue components of result (using the *= 
operator) by the result of the breakpoint function. 


13.2. Midrange transparency control 173 


struct shadow breakpoint { 
miColor color; 
miColor transparency; 
miScalar breakpoint; 


ha 


miBoolean shadow breakpoint ( 


{ 


ONAAUHF WN HP 


miColor *result, miState *state, struct shadow breakpoint *params ) 


\O 


miColor *color = mi_eval_color(&params->color) ; 
miColor *transparency = mi_eval_ color(&params->transparency) ; 
miScalar breakpoint = *mi_eval_scalar(&params->breakpoint) ; 


HR 
Ho 


result->r *= miaux_shadow_ breakpoint (color->r, transparency->r, breakpoint) ; 
result->g *= miaux_shadow breakpoint (color->g, transparency->g, breakpoint) ; 
result->b *= miaux_shadow breakpoint (color->b, transparency->b, breakpoint) ; 


return miaux_all_ channels equal(result, 0.0) ? miFALSE : miTRUE; 
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Figure 13.13: Shader source of shadow_breakpoint (p.509) 


As a shadow shader, shadow_breakpoint must also check the result color. If all three color 
components are 0.0, then the shader should return miFALSE, as in line 18. 


material "shadow _ transparent 45" 
"transparent" ( 
"color" = ‘grid", 
"transparency" 0.45 0.45 0.45 ) 
shadow 


"shadow breakpoint" ( 
"color" = "arid", 
"Cransparency"” 0.45 0.45 0.45, 
"breakpoint" 0.5 ) 
end material 


Figure 13.14: Shadows with a correct handling of transparency value of 1.0 


Using lower breakpoint values—moving the breakpoint to the left in the graph—expands the 
color range at lower transparency values. 
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Figure 13.15: Light attenuation with breakpoint at 25% transparency 


Visually, lower breakpoint values produce brighter shadow colors at lower transparency 
values. 


material "shadow_transparent_ 45" 
"transparent" ( 
‘oglor’ is Wri”, 
"transparency" 0.45 0.45 0.45 ) 
shadow 
"shadow breakpoint" ( 
"color = “erie” , 
"transparency" 0.45 0.45 0.45, 
"breakpoint" .25 ) 
end material 


Figure 13.16: Adjusting the breakpoint of the transition to transparency value 1.0 


13.3. Other parameters for the breakpoint function 


The miaux_shadow_breakpoint function expands the color values to their full range at the 
breakpoint. We can also control the degree of expansion, and therefore the intensity of shadow 
colors, by scaling the extent of the colors at the breakpoint. We’ll also define the scaling center 
around which the original color values are scaled by the extent. We’ll add these parameters to 
our breakpoint function to define function miaux_shadow_breakpoint_scale. 


double miaux_shadow breakpoint scale ( 
double color, double transparency, double breakpoint, 
double center, double extent ) 


double scaled_color = 


miaux fit(color, 0, 1, center - extent/2.0, center + extent/2.0) ; 
if (transparency < breakpoint) 

return miaux_fit(transparency, 0, breakpoint, 0, scaled_color) ; 
else 


return miaux_fit(transparency, breakpoint, 1, scaled color, 1); 


Figure 13.17: Function miaux_shadow_breakpoint_scale 
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The extent argument compresses the range of possible color values, and therefore darkens the 
shadow color. 
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Figure 13.18: Light attenuation with breakpoint=.5, center=.5, extent=.7 


We can also shift the center around which the extent is scaled. By combining this with a change to 
the breakpoint, we can create color changes that stay centered around the diagonal and therefore 
come closer to preserving the hue of the light color we will modify. 
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Figure 13.19: Light attenuation with breakpoint=.25, center=.25, extent=.25 


The shader shadow_breakpoint_scale includes the new center and extent arguments to the 
breakpoint function as parameters. 


declare shader 
color "shadow _breakpoint scale" ( 
colar *eolor mdetanwleci br. 1; 
color "transparency" default .5 


scalar "breakpoint" default 

scalar "center" default .5, 

scalar "extent" default 1 ) 
end declare 


Figure 13.20: Shader declaration of shadow_breakpoint_scale (p.510) 


The structure of the shader is the same as before with the exception of the new parameters and 
new shadow function. 
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struct shadow breakpoint scale { 
miColor color; 
miColor transparency; 
miScalar breakpoint; 
miScalar center; 
miScalar extent; 


+e 


miBoolean shadow breakpoint scale ( 
miColor *result, miState *state, struct shadow breakpoint scale *params ) 
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miColor *color = mi_eval_color(&params->color) ; 

miColor *transparency = mi_eval_ color(&params->transparency) ; 
miScalar breakpoint = *mi_eval_scalar(&params->breakpoint) ; 
miScalar center = *mi_eval_ scalar (&params->center) ; 

miScalar extent = *mi_eval_ scalar (&params->extent) ; 


result->r *= miaux_shadow_ breakpoint scale(color->r, transparency->r, 
breakpoint, center, extent) ; 

result->g *= miaux_shadow_ breakpoint scale(color->g, transparency->g, 
breakpoint, center, extent); 

result->b *= miaux_shadow_ breakpoint scale(color->b, transparency->b, 
breakpoint, center, extent); 


return miaux_all_ channels equal(result, 0.0) ? miFALSE : miTRUE; 


Figure 13.21: Shader source of shadow_breakpoint_scale (p.510) 


The shadow colors are darker than before, but you can still see some color in the lower shadow 
range using the additional breakpoint function arguments. 


material "shadow transparent 45" 
"transparent" ( 
"color" = Seria", 
"transparency" 0.45 0.45 0.45 ) 
shadow 
"shadow_breakpoint_ scale" ( 


"color" = 'erang" , 
"transparency" 0.45 0.45 0.45, 
"breakpoint" .25, 
"center" .25, 
"extent”™..25 ) 

end material 


Figure 13.22: Setting the breakpoint to 0.25 


13.4. Ashadow shader with continuous transparency change 


The breakpoint in the previous shadow creates a discontinuity in the calculation of shadow values. 
We can define functions for shadow light attenuation that have other properties. 
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double miaux_shadow_continuous ( 


{ 


double color, double transparency, double expansion ) 


return transparency 
+ miaux_ fit (transparency, 
O, 1, 
expansion * transparency * (color - transparency), 0); 


Figure 13.23: Function miaux_shadow_continuous 


This function produces a set of curves that are not symmetric around the diagonal, but do not 
have a discontinuous breakpoint as in the previous shader. 


1.0 


Shadow color 


0.0 1.0 


Shadow transparency 


Figure 13.24: Light attenuation with continuous change 


In the resulting image, the shadow transparency begins earlier in the darker range but remains 
muted throughout due to the compression of the breakpoint curves. 


material "shadow_transparent_45" 
"transparent" ( 
"Naolor" _ 'oria" P 
"transparency" 0.45 0.45 0.45 ) 
shadow 


"shadow _continuous" ( 
"color" = beri" : 
"transparency" 0.45 0.45 0.45 ) 
end material 


Figure 13.25: Shadows with continuous function for transparency 


The shader declaration includes the “expansion” argument as a parameter. 
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declare shader 
color "shadow continuous" ( 
color "color" default 111, 


color "transparency" default .5 
scalar "expansion" default 1 ) 
end declare 


Figure 13.26: Shader declaration of shadow_continuous (p.511) 


The general structure of the shader is the same as before. 


struct shadow continuous { 
miColor color; 
miColor transparency; 
miScalar expansion; 


ic 


miBoolean shadow continuous ( 
miColor *result, 
miState *state, 
struct shadow_continuous *params ) 


miColor *color = mi_eval_color(&params->color) ; 
miColor *transparency = mi_eval_ color (&params->transparency) ; 
miScalar expansion = *mi_eval_ scalar (&params->expansion) ; 


result->r *= miaux_shadow_continuous(color->r, transparency->r, expansion) ; 
result->g *= miaux_ shadow continuous (color->g, transparency->g, expansion) ; 


result->b *= miaux_shadow_ continuous (color->b, transparency->b, expansion) ; 


return miaux_all_ channels equal(result, 0.0) ? miFALSE : miTRUE; 
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Figure 13.27: Shader source of shadow_continuous (p.511) 


If we widen the midrange values by use of the expansion parameter, we still maintain the 
continuous nature of the output curves. 
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Figure 13.28: Light attenuation with continuous change with the midrange expanded by 3.0 


The expanded midrange shows much greater color intensity in the shadows. 
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material "shadow_transparent_ 45" 
"transparent" ( 
"color" = tari", 
"transparency" 0.45 0.45 0.45 ) 
shadow 
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"shadow_continuous" ( 
"color" = "grid", 
"transparency" 0.45 0.45 0.45, 
"expansion" 3 ) 
end material 


Figure 13.29: Higher contrast in midrange for transparent shadows 


13.5 Combining the material and shadow shader 


In all the previous materials, we needed to duplicate the color and transparency parameter for 
the material and shadow shaders. Frequently, we will want to share parameter values between 
the material shader and one of the other optional types we explicitly define in the material. We'll 
combine the transparent shader we’ve been using as the material shader in this chapter with the 
shadow_breakpoint_scale shader, and call the combined shader transparent_shadow. 


declare shader 
color "transparent shadow" ( 

color "“aolor', 
color "transparency", 
scalar "breakpoint", 
scalar "center", 
scalar "extent" ) 

end declare 


Figure 13.30: Shader declaration of transparent_shadow (p.511) 


Parameters are shared between the material and shadow shader by using the same shader name 
for the shadow statement, but specifying an empty parameter list. 


material "shadow_transparent_45" 
"transparent shadow" ( 
"color" = terid" , 
"Cransparency" 0.45 0.45 0.45, 
"breakpoint" .25, 


"center" 25, 
"extent" .25 ) 
shadow 


"transparent shadow" () 
end material 


Figure 13.31: Using the same shader for both the material and shadow shaders 


The body of a shader can conditionally execute different statements by examining the ray 
type stored in state->type. You can see the code of the two previous shaders inserted into Prog 204, 3.4.3. Rays 
transparent_shadow as the two blocks of the if/else conditional. 
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struct transparent shadow { 
miColor color; 
miColor transparency; 
miScalar breakpoint; 
miScalar center; 
miScalar extent; 


}3 


miBoolean transparent shadow ( 
miColor *result, miState *state, struct transparent shadow *params ) 


miColor *transparency = mi_eval_ color (&params->transparency) ; 


if (state->type == miRAY SHADOW) { 
miColor *color = mi_eval_color(&params->color) ; 
miScalar breakpoint = *mi_eval_scalar(&params->breakpoint) ; 
miScalar center = *mi_eval_ scalar (&params->center) ; 
miScalar extent = *mi_eval_ scalar (&params->extent) ; 


result->r *= miaux_shadow_ breakpoint scale(color->r, transparency->r, 
breakpoint, center, extent) ; 
result->g *= miaux_shadow breakpoint scale(color->g, transparency->g, 
breakpoint, center, extent); 
result->b *= miaux_shadow_breakpoint_scale(color->b, transparency->b, 
breakpoint, center, extent); 
return miaux_all channels equal(result, 0.0) ? miFALSE : miTRUE; 
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} 


if (miaux_all_ channels equal(transparency, 0.0) ) 
*result = *mi_eval_color(&params->color) ; 
else { 
mi_ trace transparent (result, state) ; 
if (!miaux_all_ channels equal(transparency, 1.0)) { 
miColor *color = mi_eval_color(&params->color) ; 
miColor opacity; 
miaux_ invert channels (&opacity, transparency) ; 
mi opacity set(state, &opacity) ; 
miaux_blend_channels(result, color, transparency) ; 
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} 
} 


return miTRUE; 
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Figure 13.32: Shader source of transparent_shadow (p.511) 


In the case of shadow shaders, the shader will check to see if state->type is equal to 
miRAY_SHADOW, as in line 14. Since full transparency will not require the evaluation of the 
color parameter, the shader contains three lines (lines 15, 29, and 33) that each evaluate the color 
parameter in the cases in which it is actually required. 
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material "transparent_25" 
"transparent shadow" ( 
'‘color" = "tile shader", 
"Cransparency" 0.25 0.25 0.25, 
"breakpoint" .5, 


"Senter" .5, 
"extent" .5 ) 
shadow 
"transparent shadow" () 
end material 


Figure 13.33: Shader transparent_shadow with scene from Figure 13.7 
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Chapter 14 


Reflection 


In traditional descriptions of reflection in computer graphics, the word “specular” has been used 
in a very general way to talk about the shiny quality of a surface. For example, the original 
paper on the Phong model uses “specular” in contrast to the diffuse component calculated by 
Lambert’s cosine law. Implementations of the Phong model also typically use “specular” to 
mean all non-diffuse reflection components. In mental ray, we reserve the word “specular” for 
mirror-like reflections, and use the word “glossy” for scattering reflective surfaces, like brushed 
aluminum or tarnished silver. In this sense, “glossy reflections” occur in a continuum between 
diffuse reflections at one end and specular reflections at the other. 


14.1 Specular reflections 


For specular reflection, a ray that strikes an object, the incident ray, continues in the mirror 
direction. The angle that the mirror direction makes with the surface normal vector is the same 
as the angle made by the incident ray and the surface normal. We say that the angle of incidence 
is equal to the angle of reflection. 


Incident ray 


Angle of incidence 
Surface normal vector 
Angle of reflection 


Mirror direction 


Figure 14.1: Specular reflection from a single ray 


Our first reflection shader will implement pure reflection only, without any parameters. We’ll 
call this shader specular_reflection. 


Rend 544, C.6. Illumination 


Rend 182, 7.2. Local 
Illumination vs. Caustics 
vs. Global Illumination 


Rend 118, 4.9. Reflection 


Prog 256, 3.12. Environment 
Shaders 


Prog 340, 3.26.5. RC 
Direction Functions 


Prog 322, 3.26.2. RC 
Functions 


Rend 421, 19.2. Rendering 
Quality and Performance 


Prog 91, 2.7.1.5. Trace Depth 


Prog 323, 3.26.2. RC 
Functions 


184 14 Reflection 


declare shader 


color "specular reflection" () 
end declare 


Figure 14.2: Shader declaration of specular_reflection (p.513) 


As rays reflect from an object, they may strike other objects, creating inter-object reflections. We 
also need to consider what will happen if a ray reflects from an object and then strikes no other 
objects in the scene. In Chapter 21, we'll define environment shaders that specify the color value 
that should be used for rays that strike no object in the scene. The scenes for our reflection 
shaders will use an environment shader that simply returns a single color so we can more easily 
tell when reflected rays have left the scene. 


miBoolean specular reflection ( 
miColor *result, miState *state, void *params ) 


mivector reflection. direction; 
mi_ reflection _dir(&reflection direction, state) ; 


if (!mi_trace reflection(result, state, &reflection_direction) }) 
mi_ trace environment (result, state, &reflection_ direction) ; 


return miTRUE; 
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Figure 14.3: Shader source of specular_reflection (p.513) 


In line 5 we calculate the reflection direction with the library function mi_reflection_dir. Then, 
in line 7, we use that direction to trace the reflection with mi_trace_reflection. This function 
returns a Boolean value of miTRUE as long as ray tracing is on and the ray has not exceeded the 
trace depth specified in the options block. If both of those conditions are true, then a ray leaving 
the scene without striking an object results in the color returned from the environment shader 
(or black if one has not been defined). If either ray tracing is off or trace depth has been exceeded, 
then in line 8 the function mi_trace_environment calls the environment shader explicitly if it is 
defined. If an environment shader does not exist in the camera or for the material, then black (0.0 
in all channels) is used by default. 


14.2 Reflections and trace depth 
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options "opt" 
object space 
samples 0 2 
contrast .1 .2 oe 
trace depth 5 

end options 


camera "cam" 
eutput “sara” "tif" 
Wreriertion 1.tirf" 
tecal 50 
aperture 33.3 
aspect 1.5 
resolution 300 200 
environment 
"one color" ( 
"eGqlor" 11 .9 
end camera 


material "reflect" 
"Specular reflection" () 
end material 


Figure 14.4: Specular reflection 


In the camera definition in Figure 14.4, the one_color shader is used as the argument to 
the camera’s environment statement. We'll use this camera definition (with different output Prog 111, 2.7.2.3. Other 


filenames) for all the scenes in this chapter. 


14.2 Reflections and trace depth 


Camera Statements 


Shaders and their parameters do not always specify everything we need to know to account for 
the appearance of our final rendered image. In Figure 14.5, the trace depth has been set to 5 in 
the options element. In a closer view of the scene from the previous section, we can see the 
inter-object reflections that result from our reflection shader. 


options "opt" 
object space 
samples 0 2 
COMET Sst. . hdiea oak 
trace depth 5 


end options 


material "reflect" 
"specular reflection" () 
end material 


Figure 14.5: Specular reflection between three objects 


By setting the trace depth to 0, we see no reflections at all. When a ray has been reflected more 
than the number of times specified by the trace depth, the environment shader is used to provide 


the surface color instead. 
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Options "opt" 
object space 
samples 0 2 
contrast “2 22 42 
trace depth 0 


end options 


material "reflect" 
"epecular reflection” {) 
end material 


Figure 14.6: Specular reflection disabled from zero trace depth 


By specifying a trace depth of 1, we see the reflection of the other spheres, but at that point, the 
ray has reached the trace depth and will no longer reflect, so the color of the other spheres is 


determined by the environment shader. 


options "opt" 
object space 
samples 0 2 
contrast |.2 <i 
trace depth 1 
end options 


material "reflect" 
Y‘epecular reflection" 
end material 


Figure 14.7: Specular reflection with trace depth value of 1: no inter-reflection 


By increase the trace depth to 2, we can see one reflection in the other spheres. 


options "opt" 
object space 
samples 0 2 
eontraget. <1... 
trace depth 2 


end options 


material "reflect" 
Mepecular perlection" () 
end material 


Figure 14.8: Specular reflection with trace depth value of 2: single inter-reflection 


We can see from the trace depth that the current settings of the options must be taken into 
account to understand the results we see from our shaders as we write them. We can also use 
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this dependence to our advantage. Since rendering time is dependent in part upon trace depth, 
we can adjust trace depth to lower values when our test renderings do not require complete 
accuracy. 


14.3 Glossy reflections 


For glossy reflections, the angle of reflection won’t necessarily be equal to the angle of incidence 
as in specular reflections. Instead, the reflection rays for a given surface will be contained within a 
cone centered around the mirror direction. The size of the radius of this cone corresponds to the 
degree of glossiness of the surface. Thinking about reflection this way, we can see that specular 
reflection is a special case of glossy reflection, in which the radius of the cone is zero. 


xy 


Figure 14.9: Reflection directions chosen within a cone for a glossy appearance 


Our first glossy reflection shader will only control the degree of glossiness, a quality we’ll define 
by a parameter called “shiny.” 


declare shader 
color "glossy reflection" ( 


scalar "shiny" default 5 ) 
end declare 


Figure 14.10: Shader declaration of glossy_reflection (p.513) 


The shiny parameter is used as input to the library function mi_reflection_dir_glossy, the Prog 341, 3.26.5. RC 


glossy equivalent to mi_reflection_dir. 
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struct glossy reflection { 
miScalar shiny; 
|Z. 


miBoolean glossy reflection ( 
miColor *result, miState *state, struct glossy reflection *params ) 
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miVector reflection dir; 
miScalar shiny = *mi_eval_scalar(&params->shiny) ; 
mi reflection dir glossy(&reflection dir, state, shiny); 


\O 


HR 
xo) 


if (!mi_trace_reflection(result, state, &reflection_dir) ) 
mi_ trace environment (result, state, &reflection_ dir) ; 


return miTRUE; 
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Figure 14.11: Shader source of glossy_reflection (p.513) 


Once we’ve acquired the value of parameter shiny in line 9, the structure of main part of the 
shader in lines 10-13 is the same as specular_reflection. In line 10 we determine the glossy 
reflection direction. Or rather, we should say that we determine one possible glossy direction. 
The direction values determined by mi_reflection_dir_glossy are chosen somewhere within 
the cone determined by the shiny parameter. That “somewhere” is important; mental ray 
determines successive values of the glossy direction so that the rays are well distributed within 
the cone. (We'll talk more about this in the next section.) 


As in the specular_reflection shader, if the reflected ray did not strike another object or the 
trace depth would be exceeded, we use the color of the environment in line 13 for the result of 
our shader. 


options "opt" 
object space 
samples 0 2 
contrast «21 «1 «sd 
trace depth 5 


end options 


material "reflect" 
"glossy_reflection" ( 
‘eanisy" 2) 
end material 


Figure 14.12: Glossy reflection 


A single ray sent for each glossy reflection produces the grainy look in Figure 14.12. Our 
contrast value in the options block is .1 .1 .1. Will increasing the quality of the render by 
lowering the contrast value help with grainy look of our glossy reflection? We’ll set the contrast 
to .01 .01 .01 to find out. 
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options "opt" 
object space 
samples 0 2 
Contrast .01 .01 .01 
trace depth 5 


end options 


material "reflect" 
"glossy reflection" ({ 
"Shiny” 3s ) 
end material 


Figure 14.13: Glossy reflection with increased contrast to improve quality 


The quality is a little better in Figure 14.13, but now we may be over-sampling other parts of the 
image that do not require it. We’ll need to control the amount of sampling we use for a good 
glossy reflection in the shader itself. 


14.4 Glossy reflection with multiple samples in the shader 


Rather than using a single ray in the glossy reflection cone for the color at that point, we’ll send 
several rays, and then average their resulting value. 


Figure 14.14: Multiple reflection directions averaged to produce glossy reflections 


The number of rays to send out from a glossy reflection point will be defined by a parameter to 
the shader. We'll call the shader glossy_reflection_sample, and name the parameter samples 
that defines the number of rays we’ll send out from the reflection point. 


declare shader 
color "glossy _reflection_sample" ( 


scalar "shiny" default 5, 
integer "samples" default 8 ) 
end declare 


Figure 14.15: Shader declaration of glossy_reflection_sample (p.514) 


If we are going to send out a number of rays to sample the surface that will be reflected, how 
will we choose those directions? This is that “somewhere” of the previous section. We know 
we want to choose rays within the cone. We could use pseudo-random numbers provided by 


Prog 31, 1.24. Sampling 
Algorithms 


Prog 332, 3.26.3. Sampling 
with mi_sample 


190 14 Reflection 


the standard C programming libraries, for example. The functions in the rand48 set include 
the function drand48 that returns double-precision floating point numbers between 0.0 and 1.0 
(excluding 1.0). To get a visual sense for these numbers, we’ll use drand48 to calculate x,y pairs 
that we plot in a square. 


Figure 14.16: Increasing the number of random sample points (10, 100, 1,000, 10,000) 


Notice that the points clump together in some places and are sparsely placed in others. If we use 
these kinds of numbers for our ray directions to find glossy reflection colors, we'll need a lot of 
rays to adequately represent an area. In fact, some of those rays won’t be very useful—since the 
points clump together, we’ll be sending rays in directions we’ve already been and for which we 
already have a good idea of the reflection color there. 


To address this problem, mental ray bases its calculation of sample values on a technique called 
quasit-Monte Carlo integration. The sample values obtained using this method are neither random 
(in the drand48 sense) nor are they strictly ordered. You can see in Figure 14.17 that with the 
same number of points as drand48 the area of the square is more fully covered. 
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Figure 14.17: Increasing the number of quasi-Monte Carlo sample points (10, 100, 1,000, 10,000) 


Quasi-Monte Carlo sampling is used throughout mental ray. Our access to it when we write 
shaders is provided through the library function mi_sample. The function returns any number 
of values, so we can use it for single numbers, x,y coordinates, or triplets, like three-dimensional 
points and vectors. 


Using mi_sample in a sample collection loop is the primary change to our improved glossy 
reflection shader, called glossy_reflection_sample. 
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struct glossy _reflection_ sample { 
miScalar shiny; 
miInteger samples; 


}i 


miBoolean glossy reflection sample ( 
miColor *result, miState *state, struct glossy _reflection_sample *params ) 
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miScalar shiny = *mi_eval_ scalar(&params->shiny) ; 
miUint samples = *mi_eval_ integer (&params->samples) ; 
miVector reflect dir; 

miColor reflect color; 

int sample number = 0; 

double sampled dir[2]; 
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result-sr = result->g = result=sb = 0.0; 
while (mi_sample(sampled dir, &sample number, state, 2, &samples) ) { 
mi_reflection dir glossy_x(&reflect_dir, state, shiny, sampled dir); 
if (!mi_trace reflection(&reflect color, state, &reflect dir) ) 
mi_trace environment (&reflect_color, state, &reflect_dir); 
miaux add color(result, &reflect color) ; 
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} 


miaux_ scale color(result, 1.0 / (double) samples) ; 
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return miTRUE; 
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Figure 14.18: Shader source of glossy_reflection_sample (p.514) 


After the evaluation of parameters and declaration of variables in lines 9-14, we initialize the 
result color to zero in line 16 so that we can accumulate color values with it. Lines 17-22 
contain the mi_sample loop. Calling mi_sample repeatedly and accumulating sample values is 
a typical use of the function. For each iteration of the loop, the resulting values of mi_sample 
are stored in its output arguments. When the required number of samples have been calculated, 
mi_sample returns miFALSE, and the loop terminates. 


Figure 1.19 lists the arguments of mi_sample. 


Type Argument name Description 

double* sample Array to contain result value 

int* instance The current sample number in the loop 
miState* state The current state structure 

miUshort dimension Number of elements in the sample array 
miUint* n Number of samples to take (1 if n is NULL) 


Figure 14.19: Arguments to the function mi_sample 


For our glossy reflection rays, we need a vector as a result from mi_sample. This means that 
mi_sample’s first argument will be a two-element array of doubles, sampled_dir, declared in 
line 14. We also need to specify the number of elements in the array to mi_sample for its fourth 
argument—the number 3. 


The calculation of a single reflection color in lines 18-20 is the same as glossy_ref lection, with 
the exception of the calculation of reflection direction in line 18. The function that calculates 
the reflection direction, mi_reflection_dir_glossy_x, takes an extra argument, the result from 
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mi_sample, and is designed for multiple sampling of glossy reflections. We accumulate these 
colors in line 21, and then average them for the final result in line 23. 


eptiens. "opt" 
object space 
samples 0 2 
contrast. .05 .05 .05 
trace depth 5 

end options 


material "reflect" 
"glossy _reflection_sample" ( 
"shiny" 3, 
"Samples" 8 ) 
end material 


Figure 14.20: Glossy reflection with additional rays generated at reflection point 


Even though the contrast setting in Figure 14.20 is setto .1 .1 .1,comparedto .01 .01 .01 
in Figure 14.13, the quality is still much better due to the average value produced from a number 
of rays. 


14.5 Glossy reflection with varying sample counts for reflections 


Sending out multiple reflection rays and average the resulting colors has produced a much better 
glossy reflection than using a single ray. But what if our reflection rays strike other surfaces using 
the same glossy reflection shader? 


— 


Figure 14.21: Subsequent reflections increasing the ray count exponentially 


Each subsequent reflection from a glossy surface using this shader will send out just as many 
rays, and so on, for each glossy reflection. If we are sending out eight rays for each reflection, 
then each of those eight will send out eight, or 64, which also send out eight, or 512. This increase 
in number is called an exponential explosion, since at reflection number R with N sample rays 
per reflection, we will be sending out N* total rays. To solve this problem, we need to define 
not just how many rays are used for reflections in general, but to define how many are sent out 
at each reflection. 
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Figure 14.22: Varying the number of sample rays at each reflection level 


The next shader, glossy_reflection_sample_varying defines the number of samples rays at 
each reflection. We’ll use a parameter called samples that will be an array of integers to define 
how many new reflection rays should be sent out at each reflection. Since we can’t predict how 
many reflections a single ray may traverse, we'll use the final number in the array for all the 
reflections that follow. 


declare shader 
color "glossy _reflection_sample varying" ( 
scalar "shiny" default 5, 
array integer "samples" ) 
end declare 


Figure 14.23: Shader declaration of glossy_reflection_sample_varying (p.514) 


Specifying an array of integers in the shader call in the material is the same in structure as an array 
of lights. In Figure 14.24 the array is [200, 1]. The first reflection is the one we care about the 
most, so we’re using 200 samples for it. The second and all subsequent reflections will only use 
a single ray. Depending upon the scene, this may still be good enough to create a smooth glossy 
appearance. 


options "opt" 
object space 
samples 0 2 
Contrast: i251 Jk 
trace depth 5 

end options 


material "reflect" 


"glossy reflection sample varying" 
Nehinay! 3. 
"samples" [200, 1] ) 
end material 


Figure 14.24: Glossy reflection with 200 rays at first reflection but only one for the second 


Shader glossy_reflection_sample_varying contains the same glossy reflection calculation at 
its heart, but we need to account for the varying number of samples for each reflection. 


Prog 230, 3.5. Shader 
Parameter Declarations 


Prog 207, 3.4.3. Rays 
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struct glossy reflection sample varying { 
miScalar shiny; 
int i samples; 
int n_samples; 
int samples [1]; 


hy 


miBoolean glossy reflection sample varying ( 
miColor *result, miState *state, 
struct glossy reflection sample varying *params) 
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miScalar shiny = *mi_eval_ scalar (&params->shiny) ; 

int i samples *mi_eval integer (&params->i_ samples) ; 

int n_samples = *mi_eval_integer(&params->n_samples) ; 

int *samples = mi_eval_integer(params->samples) + i samples; 

miVector reflect dir; 

miColor reflect color; 

double sampled dir[2]; 

int level = state->reflection_level, sample number = 0; 

miUint sample _ count = samples[level >= n_samples ? n_samples - 1: level]; 


if (sample count == 1) { 
mi_ reflection dir glossy(&reflect dir, state, shiny) ; 
if (!mi_trace_reflection(result, state, &reflect dir) ) 
mi_ trace environment (result, state, &reflect_dir) 
} else { 
result->r = result->g = result->b = 0.0; 
while (mi_sample(sampled_ dir, &sample number, 
state, 2, &sample count)) { 
mi_reflection_dir glossy x(&reflect dir, state, shiny, 
sampled dir) ; 
1£ (!mi_trace reflection(&reflect color, state, &reflect dir) ) 
mi_ trace environment (&reflect color, state, &reflect dir) ; 
miaux_add_color(result, &reflect color) ; 


/ 


} 


miaux_scale color(result, 1.0 / (double) sample count) ; 


} 


return miTRUE; 


Figure 14.25: Shader source of glossy_reflection_sample_varying (p.514) 


For efficiency, we treat a single sample as a special case in lines 23-25. This is the same code that 
we used before to get a single glossy reflection. But if there’s more than one sample, then we 
need to use mi_samp1e in lines 27-36 as we did in the last shader. 


The new part of the shader is the evaluation of the samples array parameter in line 15 and its use 
in line 20. Lines 13-15 are the same type of array code as we saw for lights, but the array is of 
type int, rather than miTag, as it was for lights. To specify the array element value, we’ll refer 
to the current reflection level which is available from state->reflection_level. In line 20 we 
use the C ternary operator to determine the array index: if the reflection level has exceeded the 
number of elements in the array, use the last element. (The variable level in line 19 isn’t strictly 
necessary, but it makes line 20 easier to read.) 


Now that we can control the number of samples per reflection level, we can adjust the amount 
of work our shader does to get an acceptable result. If we are very close to an object with glossy 
inter-reflections, we can specify a little more sampling for the second bounce before we use a 
single sample for all further reflections. 
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options "opt" 
object space 
samples 0 2 
COMNGEASE «1 «i. at 
trace depth 5 

end options 


material "reflect" 
"glossy _reflection_sample varying" ( 
"sning" 10; 
"Samples" [100, 4, 1] ) 
end material 


Figure 14.26: Glossy reflection with different number of samples for first three reflections 


In the course of developing a glossy reflection shader we started with the simplest case, improved 
its visual quality but with a resulting increase in rendering time, and then added efficiency controls 
to our shader by explicitly relating the sample count to the reflection level. This is often a pattern 
in shader development: get something (anything!) working, then make it good, then make it fast. 
At each step, depending upon our luck and insight, we may need to rethink our approach, but the 
process of experimenting through early shader writing in our design process can help quantify 
problems that are hard to analyze in the abstract. 


14.6 Glossy reflections and object geometry 


In the previous glossy reflection shaders, the shiny parameter has defined the blurry quality of 
the reflections. One of the implications of the way we’ve implemented glossy reflections is that 
the relative position of objects will also affect the degree to which the reflection appears to be 


blurred. 


For example, the cone of rays from an object that is near another object will be small. 


J 


Figure 14.27: Effect of object geometry on degree of glossy reflection 


But if we look at other positions on the reflecting object that are farther away from another object, 
the cone of rays will be spread far apart at the point where they strike that other object. 
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Figure 14.28: Effect of object geometry on degree of glossy reflection 


We can see this effect by rendering flat surfaces with our glossy shader. The reflections appear to 
increase in blurriness from the bottom of the two objects upward. 


options "opt" 
object space 
samples 0 2 
shadow off 
COnNtrase «kh wh wh 2 
trace depth 8 8 8 


end options 


material "reflect" 
"glossy reflection sample varying" ( 
"Samples" [100, 4, 1], 
"Shiny" 20 ) 
end material 


Figure 14.29: Variation of apparent glossiness due to object position 


As we develop shaders with increasingly realistic visual capabilities, creating scenes that test 
our conceptual model of how the shader should work becomes an important part of the shader 
development process. 


Chapter 15 


Refraction 


In Chapter 8, we explored the cumulative effects of multiple layers of transparency. In that 
shader, we assumed that the ray from the eye continues in a straight line through all the object 
instances to which our shader was attached. 


However, light passing from the air through a material like water or glass appears to bend, or Rend 123, 4.10. Transparency 
refract. Different physical materials will cause greater or lesser amounts of refraction. To quantity snceinaeiaia 

these differences, we can specify an index of refraction, a factor that defines the apparent bending 

of the light relative to that of a vacuum. This value can be measured for any transparent material. 

Intuitively, we relate higher index of refraction values with the density of the material—diamond 

is much denser than glass. 


Material Index of refraction 
Vacuum 1.0 

Air 1.00029 

Ice 1.31 


Water at68F = 1.33 
Ethyl alcohol 1.36 
Fused quartz 1.46 


Glass 1,517 
Emerald 1.576 
Sapphire Le? 

Diamond 2.417 


Figure 15.1: The index of refraction for some physical materials 


Light does not refract at all angles, however. Past a certain point, called the critical angle, light 
will reflect. We most often see this effect looking at a pool of still water. Near us, we will be able 
to see into the pool, but looking farther away from us, we see only reflections. 
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Figure 15.2: Index of refraction of 1.33 


Prog 341, 3.26.5. RC Our shaders will use mental ray library functions with the index of refraction as an argument 
penne to determine the new direction of the refracted ray. Like our reflection shaders, we’re using 
an optical property in our shader to approximate the appearance of objects in the physical 

world. 


15.1 Specular refraction of non-intersecting objects 


For our refraction shaders, we’ll make the simplifying assumption that the index of refraction is 
the same throughout the material, that the material is homogeneous with respect to refraction. 
Because the ray is a straight line, we only need to calculate new directions at surfaces where the 


shader is called. 


The simplest case is when a ray enters and exits different objects. 


entering exiting entering exiting 


Figure 15.3: A ray entering and exiting multiple objects 


However, a ray may enter and exit the same object multiple times, so we cannot make any 
assumptions that depend upon single-object intersections. 


entering exiting entering exiting 


Figure 15.4: A ray entering and exiting a single object 


To calculate the angle of the refracted ray leaving an intersection, we need to determine the index 
of refraction of either side. This means we need to determine in our shader whether we are 
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entering or exiting the instance to which that shader has been assigned. In either the multiple or 
single object case, we can count the number of intersections for this. If the count is odd, the ray 
is entering the object, if even, it is exiting. 


To count intersections, we can start at the current state in the our shader and work backwards 
toward the camera by using the parent state stored in state->parent. We’ll know when we’ve _ Prog204, 3.4.3. Rays 
gotten to the camera because it doesn’t have a parent. 


miBoolean miaux_ray_is entering material(miState *state) 


miState *s; 
miBoolean entering = miTRUE; 
for (s = state; s != NULL; s = s->parent) 
if (s->material == state->material) 
entering = !entering; 
return entering; 


Figure 15.5: Function miaux_ray_is_entering material 


The traversal of parent states in the for loop of lines 5-7 terminates when we reach the camera— 
the camera does not have a parent state, so its state->parent is NULL. By initializing entering 
in line 4 to miTRUE and reversing its logical meaning at each intersection up the chain of parent 
states, an even number of reversals sets entering to miTRUE, but an odd number sets it to 
miFALSE. 


Our first shader will define the index of refraction as a shader parameter, but we’ll assume that 
the object is in a vacuum (an index of refraction of 1.0). We also assume that for any ray, only a 
single refraction direction is possible. By analogy to specular reflections, we’ll call this specular 
refraction. (In Section 15.4, we’ll develop a further analogy to reflection in which multiple 
refraction directions are possible.) 


declare shader 
color "specular_refraction_simple" ( 


scalar "index of refraction" default 1.33 ) 
end declare 


Figure 15.6: Shader declaration of specular_refraction_simple (p.515) 


This simple refraction shader takes into account two issues that we’ll see in all our refraction 
shaders: 


1. The determination of the incoming and outgoing indices of refraction by examining the 
chain of parent states; and 


2. The use of reflection instead of refraction if the theoretical refraction angle exceeds the 
critical angle as determined by the indices of refraction. 
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struct specular_refraction_simple { 


bi 


miBoolean specular refraction simple ( 


{ 


miScalar index _of refraction; 


miColor *result, miState *state, struct specular _refraction_simple *params ) 


ONAN FWD bP 


miScalar instance ior = *mi_eval_ scalar(&params->index_of refraction) ; 
miScalar vacuum_ior = 1.0, incoming _ior, outgoing ior; 
miVector direction; 
if (miaux_ray_is entering material(state)) { 
incoming ior = vacuum_ior; 
outgoing ior = instance_ior; 
} else { 
incoming _ior instance _ ior; 
outgoing ior = vacuum_ior; 


Ne) 


} 
if (mi_refraction dir(&direction, state, incoming_ior, outgoing _ ior) ) 
mi trace refraction(result, state, &direction) ; 
else { 
mi_ reflection _dir(&direction, state) ; 
if (!mi_trace reflection(result, state, &direction) ) 
mi trace environment (result, state, &direction) ; 


} 


return miTRUE; 
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Figure 15.7: Shader source of specular_refraction_simple (p.515) 


The shader acquires the index of refraction from the shader parameters in line 8, but defines 

the index of refraction of the enclosing space as 1.0 as a local variable for clarity in line 9. 

Prog 341, 3.26.5. RC These two indices of refraction will be used by the library function mi_refraction_dir to 

ae ALA determine the direction of the refracted ray. This function, however, requires that we distinguish 

between the incoming and outgoing indices of refraction, which is done in lines 11-17 with 
miaux_ray_is_entering material in line 11. 


The function mi_refraction_dir returns miTRUE if the critical angle has not been exceeded for 
the given indices of refraction. In that case, we use that direction to send a refraction ray using 
mi_trace_refraction in line 19. However, if the critical angle has been exceeded, then we 
calculate reflection in lines 21-23 in exactly the same manner as in our reflection shaders of the 
last chapter. 


options "opt" 
object space 
samples 0 2 
COntrast:..1 .1 <1 
trace depth 5 5 5 
face both 


end options 


material "refract" 
"specular refraction" ( 
Nindex of refraction" 1.33 ) 
end material 


Figure 15.8: Specular refraction with the default index of refraction of 1.33 
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15.2. Improving the determination of the indices of refraction 


In specular_refraction_simple we made several simplifying assumptions. The first, 

implemented by function miaux_ray_is_entering, is that any ray of the same material should 

count in our inside/outside calculation. However, with the possibility of total internal reflection 

when the critical angle is exceeded, we need to check that the ray is not a reflection ray, or that 

It is a transmissive ray. The state->type field identifies the type of ray, and we can use this to Prog 204, 3.4.3. Rays 
improve our determination of the indices of refraction. 


miBoolean miaux_ray_is transmissive (miState *state) 


return state->type == miRAY_ TRANSPARENT | | 
state->type == miRAY REFRACT; 


Figure 15.9: Function miaux_ray_is_transmissive 


As we walk up the chain of parent states, we will need to check other conditions to make sure that 
we are correctly tracking the inside and outside changes of the ray. We’ll define some functions 
strictly for the clarity they will bring to the functions in which they are used. 


The two functions answer simple questions. Does the parent of a state exist? 


miBoolean miaux_parent_exists(miState *state) 


{ 


L 
a 
3 return state->parent != NULL; 
- 


Figure 15.10: Function miaux_parent_exists 


Are the shaders of two states the same? 


1 miBoolean miaux_shaders equal(miState *sl, miState *s2) 
2 4 
3 
4 


} 


return sl->shader == s2->shader; 


Figure 15.11: Function miaux_shaders_equal 


Like miaux_ray_is_entering, we will perform a similar traversal up the parent state chain, but 
we ll determine two things: 


1. Whether the ray is entering or exiting the instance (as we did in the previous shader); and 


2. The state in which this shader was last used with a transmission ray. 


Prog 208, 3.4.4. Intersection 
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miBoolean miaux_ray_ is entering ( 
miState *state, 
miState *state of this shaders previous transmission) 


miState *s; 
miBoolean ray_is_ entering = miTRUE; 
state of this shaders previous transmission = NULL; 
for (s = state; s; s = s->parent) 
if (miaux_ray_is_transmissive(s) && 
miaux parent _exists(s) && 
miaux shaders equal(s->parent, state)) { 
ray_is_entering = !ray_is_ entering; 
if (state of this shaders previous _ transmission == NULL) 
state of this shaders previous transmission = s->parent; 


} 


return ray_is_entering; 


Figure 15.12: Function miaux_ray_is_entering 


The loop in lines 8-15 implements the traversal up the parents’ states, with ray_is_entering 
declared as miTRUE in line 6 and inverted in line 12 as we did before. However, the conditional 
in the three clauses of lines 9-11 guarantee that we don’t count any reflection rays (possible if 
there is total internal reflection) and that the state from which the ray originated also contains this 
shader. The first time we find satisfy the conditions of lines 9-11, we save that state in line 14. 
Because it is the first time, and we’re going back up the state, it will be the state previous to the 
current one. The if condition of line 13 guarantees that it is only set once. 


The miState structure reserves two fields for our use in determining incoming and outgoing 
indices of refraction: state->ior_in for the incoming ray and state->ior for the outgoing 
ray. If either field hasn’t been set by a material, its value will be zero. To simplify the shader, 
we'll write two auxiliary functions that will also accept NULL as a possible value for the state 
pointer. 


The first function determines the incoming index of refraction: 


miScalar miaux_state incoming _ior(miState *state) 


{ 


miScalar unassigned ior = 0.0, default _ior = 1.0; 
if (state != NULL && state->ior_in != unassigned_ior) 


return state->ior_in; 
else 
return default_ior; 


Figure 15.13: Function miaux_state_incoming_ior 


The parallel function for the outgoing index of refraction: 
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miScalar miaux_ state outgoing ior(miState *state) 


{ 


miScalar unassigned ior = 0.0, default_ior = 1.0; 
if (state != NULL && state->ior != unassigned_ior) 
return state->ior; 
else 
return default ior; 


Figure 15.14: Function miaux_state_outgoing_ior 


We now have the components we need to set the indices of refraction for the more general case 
of object intersections. 


void miaux_set_ state refraction_indices(miState *state, 
miScalar material _ ior) 


miState *previous transmission = NULL; 
miScalar incoming ior, outgoing ior; 


if (miaux_ray_is entering(state, previous transmission)) { 
outgoing ior = material ior; 
incoming ior miaux state outgoing ior(state->parent) ; 
} else { 
incoming ior = material _ ior; 
outgoing ior = miaux_state_incoming_ior(previous transmission) ; 
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state->ior in = incoming _ior; 
state->ior = outgoing ior; 


a 
OM i 


Figure 15.15: Function miaux_set_state_refraction_indices 


The variables incoming_ior and outgoing_ior declared in line 5 are not strictly necessary, but 
are more meaningful than the corresponding state fields, which are set in lines 14 and 15. If 
we are entering the refracting material, the ray leaving the intersection point will have the index 
of refraction of the material (line 8), and the ray striking the intersection point will have the 
outgoing index of refraction of the previous state (line 9). Conversely, if we are exiting the 
refracting material, it is the incoming ray that has been traveling through the refracting material 
(line 11), whereas the outgoing ray has the same index of refraction as the ray that first entered 
this particular material. 


Using miaux_set_state_refraction_indices in shader specular_refraction clarifies the use 
of reflection in a refraction shader. 
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struct specular refraction { 


\; 


miBoolean specular refraction ( 


{ 


miScalar index of refraction; 


miColor *result, miState *state, struct specular_refraction *params ) 
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miVector direction; 
miScalar ior = *mi_eval_ scalar (&params->index_of refraction) ; 
miaux set state refraction _indices(state, ior) ; 


if (mi_refraction dir(&direction, state, state->ior_in, state->i0r) ) 
mi_ trace _refraction(result, state, &direction) ; 
else { 
mi reflection dir(&direction, state) ; 
if (!mi_trace reflection(result, state, &direction) ) 
mi trace environment (result, state, &direction) ; 


} 


return miTRUE; 


Figure 15.16: Shader source of specular_refraction (p.516) 


We have now consolidated the most difficult part of refraction calculation into a function call in 
line 10 in shader specular_reflection, with the calculation of refraction and reflection due to 
the critical angle as before. 


15.3 Using different indices of refraction 


The closer the index of refraction comes to 1.0 for an object in a vacuum, the less the light rays 
will be bent. We can experiment with our specular refraction shader to see if we get the kinds of 
results we expect from different indices of refraction. 


For example, an index of refraction of 1.1 relative to 1.0 should not bend the light rays much. 
Depending upon how far the sphere is from the background, we would expect to see an enlarged 
version of the background in the sphere’s center. 


Figure 15.17: Index of refraction of 1.1 


A rendering with an index of refraction of 1.1 using our shader shows this magnification effect. As 
the diagram suggests, the background is distorted at the edges where the rays overlap. At greater 
distances between the sphere and the background, the distortion is greater, as demonstrated by 
the upper sphere. 
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options “opt” 
object space 
samples 0 2 
SONCTSSt. «4 adi. wk 
trace depth 5 5 5 
face both 


end options 


material “refract" 
"specular refraction" ( 
"index of refraction" 1.1 ) 
end material 


Figure 15.18: Specular refraction with an index of refraction of 1.1 


If we increase the index of refraction to a larger number, the light rays are bent at an extreme 
angle. 
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Figure 15.19: Index of refraction of 2.4 


With such a large divergence of the rays from the cameraas they are refracted through the spheres, 
we can see a much larger extent of the background scene. 


options "opt" 
object space 
samples 0 2 
Contrast .1)«kh «dh 
trace depth 5 5 5 
face both 


end options 


material "refract" 
"Specular refraction" ( 
"index _of refraction" 2.417 ) 
end material 


Figure 15.20: Specular refraction with an index of refraction of 2.417 
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15.4 Glossy refraction 


In the previous shaders, we assumed that a ray could refract in only one direction based on 
surface orientation. Like reflections, refraction can also demonstrate “glossy” characteristics, 
with the direction of refraction rays varying from the direction specified by the index of 
refraction calculations. The mental ray library provides a set of functions for glossy refraction 
that correspond to the functions for reflection. 


15.4.1 Using a single glossy refraction ray 


Our first glossy refraction shader adds a control for the degree of dispersion during refraction, 
and, like the equivalent reflection shader, glossy_reflection, is called shiny. 


declare shader 
color "glossy refraction" ( 


scalar "index of refraction" default 1.33, 
scalar "shiny" default 5 ) 
end declare 


Figure 15.21: Shader declaration of glossy_refraction (p.517) 


Only a single ray is used for each glossy refraction, and we see the type of sampling we saw with 
reflection. 


options "opt" 
object space 
samples 0 2 
contrast .1 «1 «i 
trace depth 5 5 5 
face both 


end options 


material "refract" 
"qlossy_refiraction" ({ 
"index of refraction" 1.15, 
"shany" 35.) 
end material 


Figure 15.22: Glossy refraction with an index of refraction of 1.15 


The only difference between the glossy and specular shaders is the addition of the shiny parameter 
and the determination of the refraction direction in line 19. 
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struct glossy refraction { 


bi 


miScalar index_of refraction; 
miScalar shiny; 


miBoolean glossy refraction ( 


{ 


miColor *result, miState *state, struct glossy refraction *params) 


miVector direction; 
miScalar ior = *mi_eval_ scalar (&params->index_ of refraction) ; 
miScalar shiny = *mi_eval_ scalar (&params->shiny) ; 


Miaux set state refraction_indices(state, ior); 


if (mi_transmission dir glossy(&direction, state, 
state-sior in, state->ior, ‘shiny?))) 
mi trace refraction(result, state, &direction) ; 
else { 
mi_reflection_dir(&direction, state) ; 
if (!mi_trace_reflection(result, state, &direction) ) 
mi_trace_ environment (result, state, &direction) ; 


} 


return miTRUE; 


Figure 15.23: Shader source of glossy_refraction (p.517) 


The glossy appearance of the refraction is produced by the different direction function that 
returns rays distributed within a cone, mi_transmission_dir_glossy in line 15. The rest of the 
shader uses the same structure, calculating a reflection if the refraction direction exceeded the 


critical angle. 


We see that increasing the sampling rate is not sufficient to correct the grainy appearance of our 
glossy refraction. 


options "opt" 
object space 
samples 0 2 
contrast .01 .01 .0O1 
trace depth 5 5 5 
face both 


end options 


material "refract" 
"glossy_refraction" ( 
‘index of retraction” 1.15, 
"shiny" 35 ) 
end material 


Figure 15.24: Glossy refraction with an index of refraction of 1.15, sampling of .01 .01 .04 


15.4.2 Using multiple glossy refraction rays 


Our first solution to the problem of increasing refraction quality is the same as for reflections: for 
each intersection, send out additional rays and average the set of values. We will add a parameter 
to control the number of samples take per refraction: 


Prog 342, 3.26.5. RC 
Direction Functions 


Prog 332, 3.26.3. Sampling 
with mi_sample 
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declare shader 
color "glossy _refraction_sample" ( 
scalar "index of refraction" default 1.33, 


scalar "shiny" default 50, 
integer "samples" default 8 ) 
end declare 


Figure 15.25: Shader declaration of glossy_refraction_sample (p.518) 


The additional samples create a more accurate value for glossy refraction. 


options "opt" 
object space 
samples 0 2 
contrast .1 .1 .1 
trace depth 5 5 5 
face both 

end options 


material "refract" 


"glossy _refraction_sample" ( 
“index of refraction" 1.15, 
"shiny"™ 25, 
"Samples" 4 ) 
end material 


Figure 15.26: Glossy refraction with an index of refraction of 1.15 with 4 samples per intersection 


These additional rays are distributed with the library function mi_transmission_dir_glossy_x, 
which uses mi_sample to acquire well-distributed sample rays for the refraction. 


15.4 Glossy refraction 209 


struct glossy refraction sample { 
miScalar index of refraction; 
miScalar shiny; 
miInteger samples; 


be 


miBoolean glossy refraction_sample ( 
miColor *result, miState *state, struct glossy refraction_sample *params) 
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miScalar ior = *mi_eval_scalar(&params->index_of refraction) ; 
miScalar shiny = *mi_eval_scalar(&params->shiny) ; 

miUint samples = *mi_eval_ integer (&params->samples) ; 

miVector refract dir, reflect dir; 

miColor refract_color; 

int sample number = 0; 

double sample[2] ; 
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miaux set state refraction_indices(state, ior); 


14 
Lo 
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result->r = result->g = result->b = 0.0; 
while (mi_sample(sample, &sample number, state, 2, &samples) ) { 
if (mi_transmission_ dir glossy x(&refract_dir, state, 
state->ior in, state->ior, 
shiny, sample)) { 
if (mi_trace refraction(&refract_ color, state, &refract_dir) ) 
miaux add color(result, &refract color); 
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else { 
mi_ reflection dir(&reflect_dir, state); 
if (!mi_trace reflection(&refract_color, state, &reflect_dir) ) 
mi trace environment (&refract_color, state, &reflect_dir) ; 
miaux_add_color(result, &refract_color) ; 
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miaux scale color(result, 1.0 / samples) ; 
return miTRUE; 
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Figure 15.27: Shader source of glossy_refraction_sample (p.518) 


The call to mi_sample in line 21 assigns values to the two-element array of doubles, sample, 
required as an argument for mi_transmission_dir_glossy_x. The else clause in lines 29-32 
provides for total internal reflection if the refraction direction exceeds the critical angle. 


15.4.3. Controlling the number of rays per refraction 


For multiple samples per refraction, we have the same problem as we did with reflections: the 
number of rays sent per each intersection increases exponentially. Our solution will also be the 
same, and we will control the number of rays per refraction with an array of sample counts passed 
as a parameter to the shader. 
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declare shader 
color "glossy refraction _sample varying" ( 
scalar "index of refraction" default 1.33, 


scalar "shiny" default 50, 
array integer "samples" ) 
end declare 


Figure 15.28: Shader declaration of glossy_refraction_sample_varying (p.519) 


In Figure 15.29, we use 16 samples for the initial refraction and 1 thereafter. The image is roughly 
equivalent in sampling quality to the previous image, but renders in half the time. 


options "opt" 
object space 
samples 0 2 
eontrast «1 si ai 
trace depth 5 5 5 
face both 

end options 


material "refract" 
"glossy _refraction_sample varying" 
“index o£ refraction" 1.15, 
‘eniny" 35, 
"Samples" [100,4,1] ) 
end material 


Figure 15.29: Glossy refraction with an index of refraction of 1.15 with varying sample count 


Like the equivalent reflection shader, glossy_refraction_sample_varying separates a sample 
count of 1 as a special case, since it may often be the value used for successive refractive 
intersections after the initial sampling with higher counts has been finished. 
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struct glossy refraction sample varying { 
miScalar index _of refraction; 
miScalar shiny; 
int i samples; 
int n_samples; 
int samples[1] ; 


bs 


miBoolean glossy refraction_sample varying ( 
10 miColor *result, miState *state, 
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11 struct glossy refraction sample varying *params) 

12 { 

13 miScalar ior = *mi_eval_scalar(&params->index_of refraction) ; 

14 miScalar shiny = *mi_eval_scalar(&params->shiny) ; 

LS int i_samples = *mi_eval_integer(&params->i_ samples) ; 

16 int n_samples = *mi_eval_integer(&params->n_samples) ; 

17 int *samples = mi_eval_integer(params->samples) + i samples; 

18 miVector refraction dir, reflect dir; 

14 miColor refract. color, reflect .color; 

20 int sample number = 0; 

21 double sample[2] ; 

22 miUint sample count; 

23 

24 sample count = samples[state->refraction level >= n_samples ? 

25 n samples - 1 

26 state-srefraction_level] ; 

2? 

28 miaux_set_state refraction_indices(state, ior); 

2g 

30 if (sample count == 1) { 

31 if (mi_transmission_ dir _glossy(&refraction_dir, state, 

32 state->ior in, state->ior, shiny) ) 
33 mi_ trace refraction(result, state, &refraction_ dir) ; 

34 else { 

35 mi reflection _dir(&reflect_dir, state) ; 

36 if (!Imi_trace_reflection(result, state, &reflect dir) ) 

37 mi trace environment (result, state, &reflect dir) ; 

38 

39 } else { 

40 result->r = result->g = result->b = 0.0; 

41 while (mi_sample(sample, &sample number, state, 2, &sample_ count) ) { 
42 if (mi_transmission dir glossy _x(&refraction_dir, state, 

43 state->ior in, state->ior, 
44 shiny, sample)) { 

45 if (mi_trace_refraction(&refract_color, state, &refraction_dir) ) 
46 miaux_add_color(result, &refract_color) ; 

47 } 

48 else { 

49 mi reflection dir(&reflect dir, state) ; 

50 if (Imi _ trace reflection(érefilect color,.state, sreflect dir)) 
SL mi_trace_environment (&reflect_ color, state, &reflect_dir); 
52 miaux_add_color(result, &reflect_color) ; 

53 } 

54 } 

55 miaux scale color(result, 1.0 / sample count) ; 

56 } 

57 return miTRUE; 

58 } 


Figure 15.30: Shader source of glossy_refraction_sample_varying (p.519) 


Shader glossy_refraction_sample_varying has evolved through the development of the 
previous shaders in this chapter. At this point, the tangled series of if/else clauses might suggest 
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a set of utility functions to clarify the overall structure of the shader. 


15.5 Combining reflection and refraction with Phenomena 


The physical appearance of objects in the real world is hardly ever the result of a simple 
interaction of light, like pure specular reflection or refraction. Complex shading effects are 
often produced in rendering systems by creating large shaders that include all the calculations in 
a single unit. This type of implementation of a rendering effect is sometimes called a monolithic 


design approach. 


However, the shader graphs within a Phenomenon (page 41) can combine the various components 
of the interaction of light on a surface. For example, we can create a Phenomenon to blend 
refraction and reflection for a surface. Such a Phenomenon will need a shader that blends two 
colors. We can define a shader that uses a color as a blending weight between the two other 
colors. Since this could be the beginning of a set of arithmetic operators, we'll name this shader 
op_mix_ccc, an “operator” shader that mixes three colors (“ccc”). 


declare shader 
color "op mix ecc" ( 
eolor "A", 


color "5", 
color "F" ) 
end declare 


Figure 15.31: Shader declaration of op-mix_ccc (p.521) 


Shader op_mix_ccc uses color F to blend colors A and B. If the components of F are all 1.0, then 
the resulting color is A. If F is all 0.0, then the result is B. For values of F between 0.0 and 1.0, the 
result is a weighted average of A and B. 


struct op_mix_ccc { 
miColor A; 
miColor B; 
miColor F; 


bi 


miBoolean op mix _ccc(miColor *result, miState *state, struct op mix_ccc *params) 
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miColor *A = mi_eval_color(&params- >A) ; 
miColor *B = mi_eval_color(&params->B) ; 
miColor *F = mi_eval_color(&params->F) ; 
result->r miaux blend(A->r, B->r, F->r); 
result->g miaux blend(A->g, B->g, F->9); 
result->b = miaux_blend(A->b, B->b, F->b); 
return miTRUE; 


Figure 15.32: Shader source of op_-mix_ccc (p.521) 


Using shader op_mix_ccc, we can define a Phenomenon to blend the results of the two shaders to- 
gether, adding the colors produced by specular_reflection and specular_refraction. 
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declare phenomenon 
color "reflect _afid refract” -( 
scalar "lor"sagteaule 05.) 
shader "reflect" "specular reflection" () 
shader "refract" "specular refraction" ( 
"index of refraction" = interface "ior" ) 


shader’ "blend" "cpemax ccc™ ~{ 
wat _ " refrac " ; 
mu = "reflect", 
"r’ 0.5 0.5 ery 

root = "blend" 

declare 


Figure 15.33: Phenomenon reflect_and_refract 


In the reflect_and_refract shader graph, the reflection and refraction values are mixed in the 
root of the Phenomenon, shader node blend. The Phenomenon can then be used as a shader in 
a material. In Figure 15.34, the Phenomenon is used in material glass. 


material "glass" 


"reflect and refract" () 
end material 


Figure 15.34: Blending reflection and refraction with a Phenomenon 


In Figure 15.34, the blending of reflection and refraction is the same across the surface of the 
spheres. However, the ratio of reflection to refraction is dependent upon the angle formed by 
the surface and the viewing angle. Rather than using a constant value throughout, we can use 
the result of a shader that is dependent upon surface and viewing angle. For example, shader 
front_bright produces larger values when a surface faces the camera, and smaller values when 
the surface faces away. 
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material "blending weight" 


“front bright™ {) 
end material 


Figure 15.35: Shader front_bright to be used as the blending weight between reflection and refraction 


We'll use the values from front_bright as our weighting factor between reflection and refraction 
in Phenomenon shiny_edge. 


declare phenomenon 
color "shiny edge" { 
scalar “ior” default 1.05) 
shader "reflect" "specular reflection" () 
shader “refract" “specular refvaction”™ { 
"index of refraction" = interface "ior" ) 
shader "front" "Creme bright" () 
shader "blend" "op mix _ccc" ( 
wat =_ "refract", 
wea _ "reflect", 
"PMY = "Front" ) 
root = "blend" 
end declare 


Figure 15.36: Phenomenon shiny_edge 


Rendering the spheres with shiny_edge we can see more of the reflection at the edges of the 
spheres. 


material "glass" 


"shiny edge" () 
end material 


Figure 15.37: Controlling the amount of blending with shader front_bright 
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We can increase or decrease this relative difference between reflection and refraction controlled 
by front_bright by passing its values through a power function. Shader op_pow_cs raises a 
color to a power. 


declare shader 
colony. "Gp. pow cs™ .{ 


eoror “A", 
scalar "B" ) 
end declare 


Figure 15.38: Shader declaration of op_pow_cs (p.521) 


The shader uses the powf function from the standard C math library that raises a value of type 
float to the power of another float. 


struct op pow cs { 
miColor A; 
miScalar B; 


iz 


miBoolean op _pow_cs(miColor *result, miState *state, struct op pow _cs *params) 
{ 

miColor *A = mi_eval_color(&params->A) ; 

miScalar B = *mi_eval_scalar(&params->B) ; 

result->r = powf(A->r, B); 

result->g = powf(A->g, B); 

result->b = powf(A->b, B); 

return miTRUE; 
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Figure 15.39: Shader source of op_pow_cs (p.521) 


To visualize how op_pow_cs modifies the result of front_bright, we can define a preliminary 
Phenomenon that doesn’t blend reflection and refraction, but just shows the modified 
front_bright value we intend to use as the blending weight. 


declare phenomenon 
color "thick edge" ( 
scalar "thickness" default 1.0 ) 
shader "Irome*™ *frone prignt" () 


shader "edge" “op pow cs" ( 
Wau = W front W ; 
"B" = intertace "thickness". ) 
root = "edge" 
end declare 


Figure 15.40: Phenomenon thick_edge 


Using thick_edge to render the scene, the thickened dark edge of the spheres is clearly 
visible. 
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material "edge" 
"thick edge" ( 


"thickness" 3 ) 
end material 


Figure 15.41: Modifying the front_bright value with op_pow_cs in Phenomenon thick_edge 


We'll add the modification of front_bright to Phenomenon shiny_edge to create Phenomenon 
shiny_thick_edge. 


declare phenomenon 
color "shiny thick edge" ( 
scalar "ior" default 1.05, 
scalar "thickness" default 1.0 ) 
shader "reflect" "specular reflection" () 
shader "refract" "specular refraction" ( 
"index of refraction" = interface "ior" 
shader "front" "front bright" () 
shader "edge" "op pow_cs" ( 
wan = "Front " : 
"B" = interface "thickness" ) 
shader "blend" "op mix_ccc" ( 
wan = "reafract" ; 
wp "reflect" P 
" F " = " edge " ) 
root = "blend" 
end declare 


Figure 15.42: Phenomenon shiny_thick_edge 


Using a thickness parameter of 3.0, the edges of the sphere are more reflective than in our 
previous Phenomenon. 


material "glass" 
"shiny _thick_edge" ( 


"thickness" 3 ) 
end material 


Figure 15.43: Modifying the front_bright value to affect the blending weight 
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We produced a separate Phenomenon to visualize the modified front_bright weighting value 
as an intermediate step to designing a more complex Phenomenon. On the other hand, we can 
reset the root shader to other shaders in the graph to display intermediate results. Shaders not 
referenced in the Phenomenon are simply ignored. 


declare phenomenon 
color "shiny thick_edge" ( 
scalar "ior" default 1.05, 
scalar "thickness" default 1.0 ) 
shader "reflect" "specular reflection" 
shader "refract" "specular refraction" 
"index of refraction" = interface "ior" } 
shader "front" "front bright" () 
shader "edge" "op pow_cs" ( 
wan = " Front W . 
"B" = interface "thickness" ) 
shader "blend" "op mix_ccc" ( 
wa - W refract " i 
wBu = "reflect", 
a = "edge" ) 
# root = "blend" 
root = “refract" 
end declare 


Figure 15.44: A Phenomenon with the root shader replaced by an intermediate shader in the graph 


Rather than deleting the root shader line in Phenomenon shiny_thick_edge, the line is converted 
into a comment as a reminder of the original root shader. 


material "glass" 
"shiny thick _ edge" ( 


"thickness" 3 ) 
end material 


Figure 15.45: Rendering intermediate values in the shader graph by redefining the root shader 


} 


Chapter 16 


Light from other surfaces 


In all of our previous shaders that dealt with a simulation of light, we were only considering 
surtaces lit by direct illumination, in which there is a direct path from the light to that surface. 
This is only part of a full simulation of light in the physical world. We must also consider light 
that has first reflected from another surface and its contribution to the final rendered color of an 
object, that object’s indirect tllumination. In discussions of rendering, the terms local illumination 
and global illumination are often used to differentiate between the relatively simple problem of 
determining a direct path from a surface to a light source and the much more involved methods 
required when light is bouncing everywhere within a scene. 


The phrase “global illumination” implies the sum total of all the light in a scene. For efficiency 
reasons in mental ray, we instead consider direct and indirect illumination as separate categories. 
We also treat light that is reflected or refracted by a specular surface before it strikes a diffuse 
surface as a separate case, called caustics. In the real world, caustics are responsible for the pattern 
of light on the bottom of a swimming pool in sunshine. These illumination categories in mental 
ray are controlled by settings in the options block of our scene file as well as in shaders, as we'll 
see throughout this chapter. 


Specular Diffuse 
Light 


Refraction Reflection Direct 


Caustics Indirect 


Caustics 


Diffuse 


Figure 16.1: Light categories in mental ray and their relationship to material types 


Direct illumination in our shaders like lambert is calculated by the accumulation of light color 
values acquired with a loop over a list of lights passed as a parameter to the shader. No such 
straightforward loop is possible for all the surfaces that might be reflecting light toward the 
point we are going to render. The implementation in mental ray for this indirect illumination 
component creates a three-dimensional database of lighting values in the scene, the photon map, 
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before rendering begins. During rendering, shaders have access to the light estimate at a point 
stored in the photon map through functions in the mental ray API library. 


The lighting environment is simulated by sending units of energy, called photons, out from the 
lights as an analogy to the particle theory of light in physics. Photons are distributed by lights 
before rendering begins during the photon tracing phase. A photon travels on a path from the 
light, based on the origin, direction and spread in the light object. Depending upon the materials 
of the instances that the photon strikes as it bounces around in the scene, the photon’s energy will 
be absorbed to varying degrees. The position and other information about the absorption of the 
photon’s energy is recorded in the photon map. Once photon distribution has been completed 
and rendering begins, the indirect illumination at any point in the scene can be determined by 
examining some number of photons (the global illumination accuracy) in the neighborhood (the 
global illumination radius) as an estimate of the incoming light at that point. Because this method 
is an approximation, we can control its accuracy by increasing the number of photons. The 
number of photons that we’ll need will depend upon the scene as well as our requirements for 
image quality. 


In our shaders, however, the use of the photon map is simpler than this description would imply. 
We can call library functions that examine the photon map and return a light value to use in the 
shader. We also add a photon shader to the material of any object that should participate in global 
illumination calculations. 


Another indirect illumination technique, called final gathering, also creates a set of indirect 
illumination calculations before rendering begins that is saved to the final gather file. Like the 
photon map, the final gathering information can be used during rendering in a shader to include 
indirect illumination in the calculation of light at a surface. Final gathering evaluates the local 
lighting environment by sending rays from a point, distributing them throughout the hemisphere 
above that point. A technique that can be implemented in a shader, ambient occlusion, also sends 
rays throughout this hemisphere, but only determines if each ray hits an object in the scene. As 
well see in the last section of this chapter, ambient occlusion also provides a sense of the indirect 
lighting environment, but only as an approximation of the degree to which that point is blocked 
from the ambient environment in which constant lighting is assumed. 


The terminology for light simulation can vary among different rendering systems and within the 
physics literature. In mental ray, we divide up these various techniques based not on the type of 
lighting that is being simulated, but rather on implementation concerns for efficiency. 


Technique Pre-rendering storage Material shader API function 

Direct illumination None mi_sample_light in light loop 
Global illumination Photon map mi_compute_avg_radiance 

Caustics Photon map mi_compute_avg_radiance 

Final gathering Finalgather map mi_compute_avg_radiance 

Ambient occlusion None mi_trace_probe to measure occlusion 


Figure 16.2: Illumination methods and their implementation 


16.1 Using the photon map for global illumination 


Because the photon map does not record the photon’s first bounce, we’ll add global illumination 
to the lambert shader’s calculation of direct light. Rendering with lambert produces the dark 


16.1 Using the photon map for global illumination 221 


shadows that are typical of direct illumination alone. 


laght. "light" 
"spotlight" , ¢) 
erigin 1 8.40 
direction -.14 -1 -.1 
spread .912 

end light 


instance "light inst" “light” 
end instance 


material "diffuse" 
"lambert" ( 
"diffuse" 1 .95 .85, 
"lignes" ("light inst”) 
end material 


Figure 16.3: Lambert shading only 


To add global illumination to this scene, we need to make three changes: 
1. Add the global illumination contribution to the lambert shader; 
2. Add a photon shader to the materials of the object instances in the scene; and 
3. Add the statements to the options block that: 


3.1. Enable global illumination; 


3.2. Specify the number of photons to use in creation of the photon map; and 


3.3. Define the radius within which photons will be examined during rendering. 


16.1.1 Adding global illumination to the Lambert shader 


We'll call the global illumination version of the lambert shader global_lambert. It has the same 
parameters as lambert. 


declare shader 
color "global lambert" ( 


color "ambient" default O O O, 
A. db 


color "diffuse" default 1 
array light "lights" ) 
end declare 


1, 


Figure 16.4: Shader declaration of global_lambert (p.522) 


With the exception of the additional global illumination component, the structure of 
global_lambert is the same as lambert. 


Rend 20, 1.9. Stages of Image 
Generation 


Prog 340, 3.26.5. RC 
Direction Functions 


Prog 338, 3.26.4. RC Photon 


Functions 
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struct global lambert 
miColor ambient; 
miColor diffuse; 
int 1. Age; 
int n light; 
miTag light [1]; 


iz 


miBoolean global lambert ( 
miColor *result, miState *state, 
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struct global lambert *params ) 


int i, light_count, light sample count; 

miColor sum, light color, global _illumination_color; 
miScalar dot_nl; 

miTag *light; 
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miColor *diffuse = mi_eval_color(&params->diffuse) ; 
miaux_light_array(&light, &light_count, state, 
&params->i light, &params->n_light, params->light) ; 
*result = *mi_eval_ color (&params->ambient) ; 
for (i = 0; i < light count; i++, light++) { 
miaux set channels(&sum, 0) ; 
light sample count = 0; 
while (mi_sample light (&light_ color, NULL, &dot_nl, 
state, *light, &light sample count) ) 
miaux_add diffuse component (&sum, dot _nl, diffuse, &light color) ; 
if (light sample count) 
miaux_add_scaled_color(result, 


18 
19 
ou 
eal 
ae 
23 


NO NO 
1 ® 


NN N 
lO CO ~J OV 


&sum, 1.0/light sample count) ; 


} 


mi_compute_avg radiance (&global_illumination_color, state, ‘f’, NULL); 
miaux_add multiplied colors(result, &global_illumination_color, diffuse) ; 
result->a = 1.0; 


return miTRUE; 
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Figure 16.5: Shader source of global_lambert (p.522) 


In line 31 we acquire the photon map value with the library function mi_compute_avg_radiance, 
with argument ’f’ to specify the front side of the surface (as defined by the normal). The final 
argument is an optional pointer to the miIrrad_options structure which allows the modification 
of render-time global illumination and caustic options. You use a NULL pointer if you don’t want 
to specify any options. (We will use the miIrrad_options structure in Section 16.2.1.) 


In line 32 we add the global illumination to the direct illumination value acquired from sampling 
all the lights. We can simply add these values because the first object intersection when a photon 
is sent from the light is ignored—this is the direct illumination component that we handle in our 
light sampling loop and add to the results of mi_compute_avg_radiance. 


16.1.2. The photon shader 


Photon tracing occurs before actual rendering begins. An object instance includes a photon 
shader in its material in order to participate in the absorption and transmission of photon energy. 
The simplest photon shader performs those two tasks. The photon shader stores energy using 
library functions mi_store_photon or mi_store_volume_photon. The type of reflection or 
transmission (diffuse, glossy, specular) is specified by the library function that continues photon 
tracing. 
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mi_photon_reflection_diffuse 
mi_photon_reflection_glossy 
mi_photon_reflection_specular 
mi_photon_transparent 
mi_photon_transmission_diffuse 
mi_photon_transmission_glossy 
mi_photon_transmission_specular 
mi_photon_volume_scattering 


Figure 16.6: The photon tracing library functions 


Our shader will demonstrate the simplest case: storing energy for a diffuse reflection of the 
photon. 


declare shader 
color "store diffuse photon" ( 


color "diffuse color" Gefauit 1:3 1 } 
end declare 


Figure 16.7: Shader declaration of store_diffuse_photon (p.523) 


Though the role of the photon shader is quite different from those of the other shaders we have 
been writing, we use the same structure and shader argument signature as before. 
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struct store diffuse photon { 


hi 


miColor diffuse color; 


miBoolean store diffuse photon ( 


{ 


miColor *result, miState *state, struct store _diffuse photon *params ) 


miVector diffuse direction; 
miColor *diffuse_ color = mi_eval_color(&params->diffuse_color) ; 


mi_store photon(result, state); 


miaux_ multiply color(result, diffuse color) ; 
mi, reflection. dir diffuse (&diffuse.direction, state) ; 
return mi_photon reflection diffuse(result, state, &diffuse_direction) ; 


Figure 16.8: Shader source of store_diffuse_photon (p.523) 


The result pointer for a photon shader initially contains the “color” value of the photon. Since 
the photon map represents the incident light at a surface, we store the photon in the map in line 11 
before we scale the photon value by the color of the surface in line 13. Because this photon shader 
is modeling the reflective properties of a diffuse surface, we use mi_reflection_dir_diffuse to 
define the diffuse reflection direction in line 14 and then use that direction to send the photon on 
its way in line 15. 


Prog 97, 2.7.1.10. Global 
Illumination 


Rend 275, 11.2. Definitions 
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16.1.3. Global illumination statements in the options block 


Now that we have added global illumination to the lambert shader for shader global_lambert 
and created a photon shader, we need to make the adjustments to the scene file options and 
material to use them for global illumination rendering. 


In the image in Figure 16.9 you can see the result of global illumination in the lower part of the 
objects where light from the surface on which they sit has been taken into account. 


options "opt" 
object space 
Sontrasee .1 .L «hd 1 
samples 0 2 
globillum on 
globillum accuracy 500 2 
shadow on 

end options 


Liane "iene" 
"spotlight" () 
origin 1.5.0 
direction -.14 -1 -.1 
spread .912 
energy 600 600 600 
globillum photons 50000 
end light 


instance "light inst" "light" 
end instance 


material "global diffuse" 
"global lambert" ( 
"diffuse" 1 .95 .85, 
“lights” ("Light inst™} ) 
photon 
"store diffuse photon" ( 
Wditfuse color" 1 .95 
end material 


Figure 16.9: Lambert shading with global illumination 


The options block includes globillum statements to turn on photon map construction and 
use and specify the number of photons and the radius of photon acquisition used during 
rendering. 


The photon shader is specified in the material with the keyword photon. The syntax for the 
shader is the same as any other shader in the materials block. In this case, the shader has no 
arguments, so the shader name is followed as usual with an empty argument list. 


16.2 Global illumination as the ambient parameter 


We modified the lambert shader to add global illumination to its calculation of direct illumination. 
Do we need to modify our other direct illumination shaders to add global illumination? As we 
saw in Section 4.5, a shader parameter value can be the result of a named shader. Our direct 
illumination shaders like lambert have a parameter for ambient light. If we create a shader that 
only calculates global illumination, we can assign that shader to the ambient parameter. Global 
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illumination is, after all, a much better estimate for ambient light than the single color value 
typically used when the early direct illumination models were first devised. 


We'll call the shader average_radiance. 


declare shader 
color "average radiance" ( 


color "color". default 1.1 1 =) 
end declare 


Figure 16.10: Shader declaration of average_radiance (p.523) 


Since we’re only calculating the incident light in average_radiance, we just need a single 
parameter, the surface color that will attenuate the light when it is reflected from that 
surface. 


struct average radiance { 
miCcolor color; 
bi 


miBoolean average radiance ( 
miColor *result, miState *state, struct average radiance *params ) 
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miColor *color = mi_eval_ color (&params->color) ; 

mi compute avg radiance(result, state, ‘f’, NULL); 
miaux multiply color(result, color) ; 

return miTRUE; 


Figure 16.11: Shader source of average_radiance (p.523) 


With our focus on writing shaders, it would be easy to overlook mechanisms like shader graphs to Rend 278, 11.4. Shader 
create more complex effects from simple components. With average_radiance, we have created aiapt 

a shader that is by itself quite simple, but given the capabilities of the scene file, can be used in a 

variety of ways. 


In Figure 16.12, the lambert shader has replaced global_lambert in Figure 16.9. The global 
illumination component produced by named shader radiance is assigned to the ambient 
parameter of lambert. Because all the direct illumination shaders of Chapter 12 initialize their 
output color to the value of the ambient parameter and add the light loop values to that, assigning 
the global illumination component to ambient is equivalent to adding the value at the end of the 
shader as we did in global_lambert. 
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options "opt" 
object space 
GONETEEE .1 «bk «kh 2 
samples 0 2 
globillum on 
globillum accuracy 500 2 
shadow on 

end options 


shader "radiance" 
"average radiance" ( 
"color" 1 .95 .85 ) 


light "Light" 
"Spotlight" () 
Origin 15 0 
direction -.14 -1 -.1 
spread .912 
energy 600 600 600 
globillum photons 50000 
end light 


instance "light inst" "light" 
end instance 


material "global diffuse" 
"lambert" ( 
"ambient" = "radiance", 
"ditfuse": 1 2:95 .88, 
Wlaghes" {Light inet"] 
photon 
"store ditiuse photon” 
"diffuse color" 1 
end material 


Figure 16.12: Lambert shading with global illumination shader for ambient value 


A problem lurks in the separate control of the radiance-based ambient and diffuse parameters in 
the direct illumination shaders, however. If the ambient light value is white and the diffuse surface 
color of an object is red, the initial ambient color would not be white, but red. We need to scale the 
ambient value we derive from the global illumination calculations by the diffuse value, and this 
is why the color parameter for diffuse in lambert is duplicated in average_radiance. 


16.2.1 Overriding global illumination options in a shader 


Prog 329, 3.26.2. RC In shader average_radiance, we called the function mi_compute_avg_radiance with NULL for 
siecle the final argument. By passing a pointer to the mental ray structure milrrad_options, we can 
change render-time options to global illumination, final gathering and caustics from the values 


specified by the options block. 


Figure 16.13 lists the fields of the miIrrad_options structure. 
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Type 

int 
miScalar 
int 
miScalar 
miScalar 
miCBoolean 
miUchar 
miUint 
miScalar 
int 
miScalar 


Field name 


globillum_accuracy 
globillum_radius 
finalgather_rays 
finalgather_maxradius 
finalgather_minradius 
finalgather_view 
finalgather_filter 
finalgather_points 
importance 
caustic_accuracy 
caustic_radius 
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Description 


Number of global illumination photons in estimation 
Maximum distance for global illumination photons 
Number of rays in finalgather 

Maximum distance for finalgather 

Minimum distance for finalgather 

Interpret finalgather distance in pixels? 

Finalgather ray filter name 

Number of finalgather points for interpolation 
Control of number of finalgather rays 

Number of caustic photons in estimation 
Maximum distance for caustic photons 


Figure 16.13: Fields in the miIrrad_options structure passed to mi_compute_avg_radiance 


You would typically use miIrrad_options structure to change only a few of the options, using 
the values from the options block for the other fields. The convenience macro mi IRRAD_DEFAULT 
defined in shader .h initializes the fields of the structure to the options block values stored in 
the state structure. 


#define miIRRAD DEFAULT(irrad, state) do { 
(irrad) ->size 


irrad) ->finalgather rays 
irrad) ->finalgather maxradius 
irrad) ->finalgather minradius 
irrad) ->finalgather view 
irrad) ->finalgather. filter 
irrad) ->paddingl1 [0] 


->padding1 [1] 


irrad) ->globillum_accuracy 
irrad) ->globillum_radius 
irrad) ->caustic_accuracy 
irrad) ->caustic_radius 
irrad) ->finalgather points 
irrad) ->importance 


( ) 
( ) 
( ) 
( ) 
( ) 
( ) 
(irrad) 
( ) 
( ) 
( ) 
( ) 
( ) 
( 


} while (0) 


= sizeof (miIrrad_options) ; 
(state) ->options->finalgather rays; 


) 
state) ->options->finalgather maxradius; 
state) ->options->finalgather minradius; 
state) ->options->finalgather view; 
state) -soptions->finalgather filter; 


/ 


state) ->options->globillum_ accuracy; 
state) ->options->globillum_ radius; 
state) ->options->caustic accuracy; 
state) ->options->caustic_ radius; 

/* use the default one */ 

/* use the default one */ 
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Figure 16.14: The miIRRAD_DEFAULT macro in shader -h for initializing global illumination options 


We can improve our average_radiance shader by providing access to these options as parameters 
to a shader which we'll call average_radiance_options. 


Prog 232, 3.6. Parameter 
Assignments and mi-eval 


Prog 319, 3.26. Functions for 
Shaders 
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declare shader 
color "average radiance options" ( 
color ‘coLor” default 
integer "globillum_ accuracy" default 
scalar "globillum_radius" default 
integer "finalgather rays" default 
scalar "finalgather_maxradius" default 


scalar "finalgather_minradius" default 
integer "finalgather view" default 
integer "finalgather filter" default 
integer "finalgather points" default 
scalar "importance" default 
integer "caustic accuracy" default 
scalar "Caustic radius" default 
end declare 


Figure 16.15: Shader declaration of average_radiance_options (p.524) 


We don’t want to set the values in the miIrrad_options fields unless we explicitly specify the 
corresponding parameter for the shader. We use a default parameter value of -1 (or -1.0 for the 
scalars) as a flag to indicate if the parameter value hasn’t been changed, since -1 is not a valid value 
for any other options. 


We have to evaluate all the parameters to check if any have been set when the shader is used in the 
material, that is, if the value is not longer the flag value of -1. We’ll define two auxiliary functions 
to simplify the shader code. The first will be used for the integer values (and those parameters 
that can be correctly cast to an integer, like miCBoolean). 


1 void miaux_set_integer_if not_default ( 

2 miInteger *result, miState *state, miInteger *param) 
3 { 

4 miInteger use default flag = -1; 

2 miInteger param_value = *mi_eval_integer (param) ; 

6 if (param_value != use default flag) 

a 
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*result = param value; 


} 


Figure 16.16: Function miaux_set_integer_if_not_default 


The corresponding function for scalars is identical in structure. 


void miaux_set_scalar_if not default ( 
miScalar *result, miState *state, miScalar *param) 


miScalar use_default flag = -1.0; 


miScalar param value = *mi_eval_ scalar(param) ; 
if (param_value != use default flag) 
*result = param value; 
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Figure 16.17: Function miaux_set_scalar_if_not_default 


Note that a miState pointer is passed as an argument to these two functions, though the state 
variable is not present the in the function body. The mi_eval_* functions require the miState 
variable to be named “state”. Note also that the use of -1 as a flag (indicating that a parameter has 
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not been set) is buried inside these two functions. We are at the limit of good C programming 
style in the quest for clarity of the source code. The macro suite mi_eval_* and the macro 
miIRRAD_DEFAULT are convenient, but at a price of errors that may be difficult to uncover. 


Creating the milrrad_options structure for mi_compute_avg_radiance dominates our formally 
two-line shader. 


struct average radiance options { 
miColor color; 
miInteger gi accuracy; 
miScalar gi_radius; 
miInteger fg rays; 
miScalar fg maxradius; 
miScalar fg_minradius; 
miInteger fg view; 
miInteger fg filter; 
miInteger fg points; 
miScalar importance; 
miInteger caustic_accuracy; 
miScalar caustic radius; 


F 


miBoolean average radiance options ( 


{ 


miColor *result, miState *state, struct average radiance options *params ) 


miColor *color = mi_eval_color(&params->color) ; 
miIrrad_options options; 
miIRRAD DEFAULT (&options, state) ; 


miaux_set_integer_ if not_default ( 

&options.globillum_accuracy, state, &params->gi_ accuracy) ; 
miaux_set_scalar_if not default ( 

&options.globillum_radius, state, &params->gi_ radius) ; 
miaux_set_integer if not default ( 

&options.finalgather_rays, state, &params->fg_ rays) ; 
miaux set scalar if not_default ( 

&options.finalgather_maxradius, state, &params->fg maxradius) ; 
miaux_set_scalar if not default ( 

&options.finalgather minradius, state, &params->fg _minradius) ; 
mMiaux_set_integer if not default ( 

(miInteger*) &options.finalgather view, state, &params->fg_ view) ; 
miaux_set_ integer if not default ( 

(miInteger*) &options.finalgather filter, state, &params->fg filter) ; 
miaux_set_integer if not default ( 

(miInteger*) &0options.finalgather points, state, &params->fg points) ; 
miaux set _scalar_ if not default ( 

&options.importance, state, &params->importance) ; 
miaux set_integer if not default ( 

&options.caustic_ accuracy, state, &params->caustic_ accuracy) ; 
miaux_set_ scalar _ if not default ( 

&options.caustic radius, state, &params->caustic radius) ; 


mi compute avg radiance(result, state, ‘f’, &options) ; 
miaux_ multiply color(result, color) ; 


return miTRUE; 


Figure 16.18: Shader source of average_radiance_options (p.524) 


The milrrad_options structure is declared in line 20 and filled with the values from the options 


Rend 178, 7.1. Photon 
Mapping vs. Final 
Gathering 
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block in the scene with the miIRRAD_DEFAULT macro in line 21. Once the fields are optionally set 
in Lines 23-44, the average radiance is computed as before in line 46, but with a pointer to the 
milrrad_options struct as the last argument, rather than NULL. 


The change to average_radiance_options with the globillum_accuracy parameter set to 1000 
is the only change to the scene in Figure 16.9. The quality of the shading under the sphere is 
improved with the use of more photons. 


options "opt" 
object space 
SCGntraet «2 «i «hk tL 
samples 0 2 
globillum on 
globillum accuracy 500 2 
shadow on 

end options 


shader "radiance" 
"average radiance options" ( 
Yoosor® 1° 59>. 28S, 
"globillum_accuracy" 1000 ) 


Light “"Light”™ 
Kepotlight"™ () 
origin 1 5 0 
direction -.14 -1 -.1 
spread .912 
energy 600 600 600 
globillum photons 50000 
end light 


instance “light inst" "light" 
end instance 


material “global diffuse" 
"lambert" ( 
"ambient" = "radiance", 
"diffuse" 1 .95 .85, 
eiience” ("light anst")] } 
photon 
"store diffuse photon" ( 
"diffuse color" 1 .95 
end material 


Figure 16.19: Lambert shading with global illumination shader for ambient value with option override 


The more flexible shader average_radiance_options is not without its cost—every parameter 
must be evaluated to see if it is mot the flag value of -1, which means to leave that field with its 
default value. If no options are to be changed, the shader average_radiance will therefore be 
more efficient. 


16.3 Final gathering 


The shaders we’ve developed in this chapter will also take final gathering into account if it is 
enabled. Like the construction and use of the photon map, final gathering is specified in the 
options block. When we add final gathering to the scene in Figure 16.9, the areas under the 
objects which require a large number of photons become more evenly shaded. 
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options "opt" 

object space 

Contrast «1 «ltl «i db 

samples 0 2 

globillum on 

globillum accuracy 0 2 

shadow on 

finalgather on 

finalgather accuracy view 500 30 4 
end options 


shader "radiance" 
"average radiance" () 


Lento" Light. 
“gpotlight" {) 
Origin 1°sae 
direction -.14 -1 -.1 
spread .912 
energy 600 600 600 
globillum photons 50000 
end light 


instance "light ingik" "Itong" 
end instance 


material "global _ diffuse" 
"lambert" { 
"diifuge" 1 .95..85, 
"ambient" = "radiance", 
"lighta" {*"light inst"] | 
photon "store diffuse photon" () 
end material 


Figure 16.20: Final gathering added to the result of the photon map 


For scenes in which an accurate lighting simulation is not a priority, final gathering alone may be 
sufficient and faster than photon mapping. 


options "opt" 

object space 

COnrcras. «1 «dt «kh 4 

samples 0 2 

shadow on 

finalgather on 

finalgather accuracy view 500 30 4 
end options 


material "global diffuse" 
"lambpert” { 
“at fies F771) 495) BS, 
"ambient" = "radiance", 
Nlagnte”: ("light Anee) ) 
photon "store diffuse photon" () 
end material 


Figure 16.21: Final gathering only 


For complex diffuse scenes, we can also increase the final gathering trace depth, which controls Prog 100, 2.7.1.11. Frame 
how many reflections and refractions each final gather ray will use to calculate its color value. guess 


Rend 190, 7.6. Caustics 
Prog 41, 1.32. Caustics 
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Final gather trace depth is specified in the options block, and defines the trace depth for three 
categories and the maximum total of interactions. 


finalgather trace depth reflection-max refraction-max diffuse-max total 


Figure 16.22: The trace depth arguments final gathering 


For example, by setting the diffuse reflection interactions to 2 with 2 0 2 2, the intensity of the 
light on the ground plane resembles Figure 16.21 which included the photon map. 


options “opt" 

object space 

Sontreas= «1 .1 .1ld 

samples 0 2 

shadow on 

finalgather on 

finalgather accuracy view 500 30 4 

finalgather trace depth 2 0 2 2 
end options 


material "global diffuse" 
"lambert" ({ 
"diffuse" 1 .95 .85, 
"ambient" = "radiance", 
"lights" ["light inst"] ) 
photon "store diffuse photon" () 
end material 


Figure 16.23: Final gathering only; two diffuse bounces to improve accuracy 


Using final gathering alone may be preferable to the photon map for scenes in which only a few 
diffuse bounces of light are required. For scenes with complex light interactions like architectural 
simulations in which a high degree of accuracy is required, photon mapping augmented with 
final gathering will be a more efficient solution than final gathering alone with an increased trace 


depth. 


16.4 Caustics 


Like global illumination, caustic effects in mental ray are also implemented with a photon shader 
included in a material. However, rather than storing incoming illumination and calculating a new 
direction for the photon as it bounces off the surface, caustics require that photon shaders transmit 
the photon through the surface. In the case of a refracting surface, the refraction direction is 
calculated using an index of refraction as we did for material shaders. 


To create a surface that will generate interesting caustic patterns, we’ll jump ahead to Chapter 17 
and add a square with displacements like the scene in Figure 17.16. Rendering the scene with 
front_bright displays the wave-like shape of the displacements on the square. 
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material "displace" 
"front bright" () 
displace 
"displace ripple" ({ 
"Center" .2 .5 OQ, 
"frequency" 20, 
"amplitude" .01 ) 
"displace ripple" ( 
tecenter" .8 8 0, 
"frequency" 20, 
Yampolitude" .01.) 
"displace ripple" ( 
enter" .o oe “Oy 
"frequency" 20, 
"amplitude", .01: ) 
end material 


Figure 16.24: A square with displacements added to the scene 


A photon shader that transmit photons to create caustics will typically include the transparency 
of the surface to allow for a modification of the transmitted color. To create caustic effects, the 
photons need to be focused and dispersed by the refracting action of the surface, so the shader 
may also specify an index of refraction. 


declare shader 
color "transmit_specular_photon" ( 


color "transparency" default 11 1, 
scalar "index of refraction" default 1.33 ) 
end declare 


Figure 16.25: Shader declaration of transmit_specular_photon (p.525) 


To create caustics, the caustic option must be set to on and a photon shader added to a material Prog 96, 2.7.1.9. Caustics 
that includes a refracting material shader that transmits light. 
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options "opt" 

object space 

contrast «lL ,1..2 2 

samples -1 2 

shadow on 

displace on 

max displace .2 

caustic on 

caustic accuracy 500 .1 
end options 


material "refract" 
"specular refraction" ( 
"index of refraction" 1.5 ) 
displace 
"displace ripple" ( 
"Center" .2 .5 0, 
"frequency" 20, 
"amplitude" .01 ) 
"displace ripple" ( 
"center": .6 .8 0, 
"frequency" 20, 
"amplitude" .01 ) 
"displace ripple" ( 
"“esenter" .8 «2 0, 
"frequency" 20, 
"amplitude" .01 ) 


photon 
"transmit _specular_photon" ( 
"index of refraction" 1.5 ) 
end material 


Figure 16.26: Transmission of photons through a displaced surface to create caustics on a diffuse surtace 


The pattern of bright circles on the lower surface correspond to the concentrating and diffusing 
effects of the displaced pattern of the surface to which the shader transmit_specular_photon is 
attached. 


struct transmit specular photon { 
miColor transparency; 
miScalar index _of refraction; 


be 


miBoolean transmit specular photon ( 
miColor *result, miState *state, struct transmit specular photon *params ) 
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miVector photon direction; 
miColor new energy; 


} 
oO 


a 
NP 


miaux multiply colors(&new_ energy, result, 
mi eval color (&params->transparency) ) ; 
mi refraction dir(&photon direction, state, 1.0, 
*mi_eval_scalar(&params->index_of refraction) ) ; 
mi_ photon transmission specular(&new_energy, state, &photon_ direction) ; 
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return miTRUE; 


jn 
\O 


Figure 16.27: Shader source of transmit_specular_photon (p.525) 


The incoming light energy is represented in the result argument (line 7). Before the photon 
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is transmitted in line 16, the incoming energy is attenuated by the transparency parameter in 
lines 12-13. The refraction direction in lines 14-15 is calculated by mi_refraction_dir in the 
same manner as the refraction shaders of Chapter 15. Here, however, we’re not sampling the scene 
with a new ray, but sending a photon in the refraction direction to represent the transmission of 


light energy. 


Adding global illumination brightens the lower parts of the objects as light from the caustics are 
now included in the total light calculation. 


options "opt" 
object space 
GCOMETACE. «4 ek wk 
samples -1 2 
shadow on 
displace on 
max displace .2 
globillum on 
globillum accuracy 500 2 
caustic on 
Gauistic accuracy 500: v1 
end options 


material "refract" 
"specular refraction" ({ 
Mindex ©f wetraction"™ 1.5 ) 


displace 
"displace ripple" ( 
"center" .2 .5)0, 
"frequency" 20, 
"amplitude" .01 ) 
"displace ripple" ( 
"center" .6 .8 U0; 
"frequency" 20, 
Yamplitude® 01 } 
"displace ripple" ( 
‘Oencer" 28 .2°O; 
"frequency" 20, 
"amplitude" .01 ) 
photon 
"transmit specular photon" ( 
"index of refraction” 1.3.) 
end material 


Figure 16.28: Caustics and global illumination used together 


16.5 Visualizing the photon map 


In Chapter 6, “Color from orientation,” we made a shader that converted the surface normal 
into a color. A vector isn’t a color, after all, but by treating it as one we are able to visualize 
the orientation of the surface. This could be a very useful technique when we are checking for 
possible problems in the construction of our geometric models. 


In a similar vein, we can set the global illumination options to values that would not be useful 
for producing final imagery, but can help us understand the way that the photon tracing process 
distributes photons to construct the photon map for its use in rendering. 


In the photon tracing phase, the energy of a light emitting photons is divided up equally among 
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all the photons. If we set the photon count to a low number, then each photon will have a large 
amount of this simulated energy. If the radius is small, then only a small area of the scene will be 
near enough to a photon—within the radius—to use the photon energy in the global illumination 
value. The photon positions will be quite visible as very bright circles with the photon position 
in the center. 


light "light" 
"spotlight" {) 
origin 15 0 
direction -.14 -1 -.1 
spread .912 
energy 1500 1500 1500 
globillum photons 100 
end light 


material "indirect" 

"average radiance options" ( 
"globillum_accuracy" 100, 
"globillum_radius" .1 ) 

photon 
"store diffuse photon" ( 

"aitiuse color" 1. .95 .85 } 


end material 


Figure 16.29: Global illumination only: 100 photons with a radius of .1 


If we only increase the radius, but leave the photon count and light energy value unchanged, the 
area around the photon that is affected by its energy is larger but the resulting intensity is less. 
Intuitively, it seems that the photon is distributing its energy in a larger area. 


Laghnt Light" 
"Spotlight" () 
origin 1 5 0 
direction -.14 -1 -.1 
spread .912 
energy 1500 1500 1500 
globillum photons 100 
end light 


material "indirect" 

"average radiance options" ( 
"globillum_ accuracy" 100, 
"globillum_ radius" .3 ) 

photon 
"store diffuse photon" ( 

"diffuse coltor®"’ 1.95 .85 } 


end material 


Figure 16.30: Global illumination only: 100 photons with a radius of .3 


Increasing the number of photons to 1,000 but returning to the smaller radius of 0.1, we can see 
better how the photons will be distributed in the scene at higher photon counts. 
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"‘spotiight” '() 

origin 1°50 

direction -.14 

spread .912 

energy 1500. 1500. 1500 

globillum photons 1000 
end light 


material "indirect" 

"average radiance options" ( 
"globillum_ accuracy" 1000, 
"globillum. radius" ).1°-) 

photon 
"store diffuse photon": ( 

"diffuse coior® 1...95 
end material 


Figure 16.31: Global illumination only: 1000 photons with a radius of .1 


By widening the radius, we can smooth out the effect of the photon energy but at the expense of 


detail. 


Lignt “*lignt* 

"spotlight" 4) 

origin i 5 0 

direction -.14 

spread .912 

energy 1500 1500 1500 

globillum photons 1000 
end light 


material "indirect" 


"average radiance options" ( 
"globillum_accuracy" 1000, 
"globillum_radius" .3 ) 

photon 
"store diffuse photon" ( 

"dattuse color’: 1.155 
end material 


Figure 16.32: Global illumination only: 1000 photons with a radius of .3 


With more photons, the image becomes smoother still. We can also see more clearly the light 
interaction between the objects and the floor. The contribution of the direct light to the final 
color of the floor is much greater than the indirect illumination, so we only see the result of the 
photon calculation in a subtle lightening of the shadows in Figure 16.9. 
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light "light" 

Seapotlagnt” {) 

ersqin 1.5.0 

direction -.14 

spread .912 

energy 1500 2500 1500 

globillum photons 10000 
end light 


Material "indirect" 

"average radiance options" ( 
"globillum_accuracy" 10000, 
"globillum radius" .3 ) 

photon 
“store diffuse photon" { 

"dittuee, cotor" 1 1.95 
end material 


Figure 16.33: Global illumination only: 10000 photons with a radius of .3 


In Figure 16.33 we can still see an uneven distribution of photons, particularly on the sphere. 
However, in a typical scene, additional lighting and texturing of the surface may make such 
artifacts very difficult to detect. Larger numbers of photons will lengthen rendering time; by 
using a shader like average_radiance_options we can get a feeling for the relationship between 
necessary quality and efficiency. 


16.6 Ambient occlusion 


In global illumination, we are concerned with the light that is missing from a scene when only 
direct illumination is considered. We can also invert the problem, and consider the variable way 
that light is blocked, or occluded, from a point in the scene by the objects between it and the 
light. If we assume that there is an even distribution of ambient light surrounding the objects 
in our scene, then the amount of light that reaches a point is due solely to occlusion from other 
objects. Because we consider the degree to which we are blocked from this ambient environment, 
a rendering technique that uses this idea has been labeled ambient occlusion. 


In ambient occlusion, we aren’t concerned with actual lights, but only with the geometric 
relationship of the objects in the scene. Consider a flat object underneath two blocks. If 
we send rays out from a point underneath one of the blocks, we can count how many rays hit 
another object, and how many don’t. The ratio of hits to total rays is a measure of the occlusion 
at that spot. Since light would be blocked, the higher this occlusion percentage, the darker we 
would expect that spot to be. 
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Figure 16.34: Calculating ambient occlusion: 12 intersections out of 35, or 34% occlusion 


We can do this same test at any point in the scene, and not only two-dimensionally, as in these 
diagrams, but throughout the hemisphere that surrounds the point. 
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Figure 16.35: Calculating ambient occlusion: 16 intersections out of 35, or 46% occlusion 


Given enough rays (and we’ll see how to efficiently use “enough” in the next section) we get 
a good proportional measure of occlusion. This method also nicely conforms to our common 
sense—when an object is near another object, we expect that object to block light, and it would 
be darker there. With 66% occlusion for the point in Figure 16.36, we expect it to be darker than 
the points in the previous two diagrams. 


ee 


Figure 16.36: Calculating ambient occlusion: 23 intersections out of 35, or 66% occlusion 


16.6.1 Sampling the environment by tracing rays to detect occlusion 


The degree of occlusion corresponds intuitively to darker areas. Our ambient occlusion shader 
will return a color based on the occlusion percentage. Its single parameter will control how many 
sampling rays we send into the environment to detect other objects. 
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declare shader 
color "ambient occlusion" ( 


integer "samples" default 8 ) 
end declare 


Figure 16.37: Shader declaration of ambient_occlusion (p.526) 


If we send rays out in a regularly spaced pattern (as in the diagrams), we will, as usual, 
be subject to aliasing as an artifact of poor sampling. We can use the mi_sample function 
as we did in glossy reflection and refraction to vary our sampling rays to get a good 
approximation with a small number of rays. But what are we varying? The API library function 
mi_reflection_dir_diffuse_x calculates diffuse reflections like mi_reflection_dir_diffuse, 
but also takes as an argument a two-dimensional result from mi_sample. This gives us a well- 
distributed set of rays in the hemisphere above a point. We can specify how many rays we will 
average for the final result with the final argument to mi_sample that controls the number of 
times the loop will execute. The structure of shader ambient_occlusion is dominated by this 
mi_sample loop to create the vectors we’ll use to examine the scene above the current point. 


struct ambient occlusion { 
miUint samples; 


miBoolean ambient occlusion ( 
miColor *result, miState *state, struct ambient occlusion *params) 
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miUint samples = *mi_eval_ integer (&params->samples) ; 
miVector trace direction; 

int object hit = 0, sample number = 0; 

double sample[2], hit fraction, ambient_exposure; 


\O 
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while (mi_sample(sample, &sample number, state, 2, &samples)) { 
mi reflection dir diffuse x(&trace direction, state, sample) ; 
if (mi_trace probe(state, &trace direction, &state->point) ) 
object hit++; 
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hit fraction = ((double)object hit / (double) samples) ; 
ambient exposure = 1.0 - hit fraction; 

result->r = result->g = result->b = ambient exposure; 
result->a = 1.0; 
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return miTRUE; 
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Figure 16.38: Shader source of ambient_occlusion (p.526) 


The heart of the shader is the call to mi_trace_probe in line 15. This function only tests to see 
whether an object exists in the direction of a ray from a point without calling any shaders for the 
material at the intersection point. If it returns miTRUE, we increment the counter object_hit in 
line 16. The number of iterations of the mi_sample loop is specified by the samples parameter, 
and therefore passed as the last argument to mi_sample. 


The hit_fraction in line 18 is the ratio of number of hits to total samples. Since we think of 
this fraction as the amount of occlusion, we can subtract it from 1.0 in line 19 to represent the 
amount of exposure, which is what we assign to our output color in line 20. 
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Rendering with ambient_occlusion and a samples value of 10 produces the image in 
Figure 16.39. 


material "amb occlude" 
"ambient occlusion" ( 
"samples" 10 ) 


end material 


Figure 16.39: Ambient occlusion using ten samples to determine the degree of occlusion 


Increasing the samples value improves the image quality. The sense that we are seeing a simulation 
of light is quite strong, even though we did not actually make use of light instances in our shader. 
Instead, the assumption of a general hemisphere of light allows us to evaluate the degree of 
exposure and turn that into a color value in the ambient_occlusion shader. 


material "amb occlude" 
"ambient occlusion" ( 
"samples" 200 ) 


end material 


Figure 16.40: Using more ambient occlusion samples to improve image quality 


16.6.2 Restricting ray length in occlusion detection 


By default, the mi_trace_probe function will return miTRUE if the probe ray intersects any object 
instance in the scene database. Objects that are very distant are not as important in blocking 
light as objects nearby, and we may not want to count their contribution to the hit fraction. 
In addition, these objects may not be in the geometry cache in memory, but will be loaded as 
a consequence of mi_trace_probe, with a resulting cost in rendering time, even though their 
contribution is not worth the expense. 


If we can specify a length for our probe rays, then we can limit the number of objects we use in 
the calculation of ambient occlusion. 
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Figure 16.41: Calculating ambient occlusion using a cutoff: 8 intersections out of 35, or 23% occlusion 


Our shader with ray length control is called ambient_occlusion_cutoff. We’ll define the 
maximum length distance with the parameter cutoff_distance. 


declare shader 
color "ambient occlusion cutoff" ( 


integer "samples" default 8, 
scalar "cutoff distance" default 1, ) 
end declare 


Figure 16.42: Shader declaration of ambient_occlusion_cutoff (p.527) 


By using a cutoff distance of 1, the probe rays sent from the upper parts of the objects no longer 
reach as many objects, and therefore are lighter than without the cutoff. 


material "amb_occlude" 
"ambient occlusion cutoff" ( 
"Samples" 200, 
"cutott distance" 1 ) 


end material 


Figure 16.43: Ambient occlusion calculated with sample rays of restricted length 


Prog 327, 3.26.2. RC We can define the length of our probe rays with the library function mi_ray_falloff. Its 
cia arguments specify the beginning and ending of a falloff distance, and it remains in effect for all 
rays cast in the shader. For functions that trace rays to evaluate colors, the start and stop 
arguments produce an interpolation between the evaluated color and the environment color for 
a ray with a length between start and stop. To use mi_trace_probe, we'll set start and stop 

to the same value, the parameter cutoff_distance. 
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struct ambient occlusion cutoff { 
miUint samples; 
miScalar cutoff distance; 


iz 


miBoolean ambient _occlusion_cutoff ( 
miColor *result, miState *state, struct ambient occlusion cutoff *params) 
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miUint samples = *mi_eval_ integer (&params->samples) ; 
miScalar cutoff distance = *mi_eval_scalar(&params->cutoff distance) ; 
miVector trace direction; 
int object_hit = 0, sample number = 0; 
double sample[2], hit_fraction, ambient exposure, 
fallorr etart, Lallotr stop; 
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falloff start = falloff stop = cutoff distance; 
mi_ray falloff(state, &falloff start, &falloff stop); 
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while (mi_sample(sample, &sample number, state, 2, &samples)) { 
mi_reflection dir diffuse x(&trace direction, state, sample); 
if (mi_trace probe(state, &trace direction, &state->point) ) 
object hit++; 
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} 


hit fraction = ((double)object hit / (double) samples) ; 
ambient exposure = 1.0 - hit fraction; 

result->r = result->g = result->b = ambient exposure; 
result->a = 1.0; 
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mi_ray falloff(state, &falloff start, &falloff_ stop); 
return miTRUE; 
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Figure 16.44: Shader source of ambient_occlusion_cutoff (p.527) 


The mi_samp1e loop in lines 19-23 is the same as ambient_occlusion. By callingmi_ray_falloff 
in line 17, the rays sent by mi_trace_probe are set to the cutoff distance defined as the parameter 
cutoff_distance. Note that the arguments to mi_ray_falloff are pointers. The arguments are 
set to the current falloff values; these values should be used to restore the previous falloff values, 
as we do in line 29. 


Specifying a falloff distance for rays is a general technique that can allow for a considerable 
increase in performance since only local geometry may be involved and the shader can benefit 
from mental ray’s caching mechanisms. Even a very short cutoff distance for ambient occlusion 
in complex scenes can help make geometric details more clearly visible in an apparently realistic 
way. 


Part 4: Shape 


Chapter 17 


Modifying surface geometry 


So far, our shaders have only been calculating color values—the type of the result argument 
has been a pointer to miColor. Many shaders depend upon the shape of a surface to calculate 
the way in which light determines the resulting color value. By modifying the surface geometry 
in a shader, we can affect the calculation of that color. In a displacement shader, the result is 
a miScalar that defines how far along the surface normal the current point should be moved. 
Displacement shaders can provide geometric detail at a scale that would be very difficult to model 
directly. 


With displacement shaders, it’s possible that the terminology can be misleading. A displacement 
shader isn’t “shading”—the term “shader” has been generalized over the course of mental ray’s 
development to mean any functional addition that can be specified at run-time. The modification 
of surface shape defined by displacement shaders even happens before “rendering”—shading 
proper—actually begins. The material shaders then determine color values for the newly 
constructed geometry. 


17.1. Surface position and the normal vector 


The normal to a surface is the direction that is at right angles to it. Intuitively, you think of it 
as the direction in which the surface is pointing. As we saw in the various direct illumination 
models in Chapter 12, there is a relationship between the orientation of the surface with respect 
to the light and the way that the surface will be shaded. 


Normal 
eee Light 


Surface 


Figure 17.1: The orientation of the light ray at a point on the surface 


In a flat surface the normal vector is the same everywhere on the surface. Though we typically 
think of a single normal as describing the entire surface, we can imagine calculating the normal 
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at various places on the surface. We would just get the same value. 


Figure 17.2: The orientation of a flat surface 


If we define a function that relates surface position to a change of position along the normal, then 
we have specified a new geometric shape for that surface. 


Figure 17.3: Points on the surface are displaced to new positions 


Displacement shaders define this distance along state->normal to which each point is moved, 
the miScalar value stored in the result pointer. 
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Figure 17.4: The new surface with its normal vectors 


The new surface will also have new normal vectors with resulting change to the results of any 
material shader that takes state->normal into account. 


If a displacement shader modifies the result value, rather than assigning a new value to it, the 
shader can be chained ina list (as in Section 4.4), with successive modifications to the displacement 
amount. (We’ll use three displacement shaders in a list in Section 17.3.) 


17.2, Asimple displacement shader 


Displacement shaders are defined in the material with the displace statement. To show the 
resulting difference in surface geometry, we'll start with the lambert shader for the material 
shader of a polygon light from the side. 
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material "lambert" 
"lambert" ( 


"diffuse" 111, 
niignte” {"iagnt inst") ) 
end material 


Figure 17.5: A polygon with lambert used as its material shader 


We’ll base our first displacement shaders on a sinusoidal function that maps an input value to a 
sine wave with a given frequency and amplitude. 


double miaux_sinusoid(double v, double frequency, double amplitude) 


{ 
} 


return sin(v * frequency * M PI * 2.0) * amplitude; 


Figure 17.6: Function miaux_sinusoid 


Our first displacement shader, displace_wave, will define the frequency and amplitude 
arguments to miaux_sinusoid as parameters to the shader. 


declare shader 
scalar "displace wave" ( 
scalar "frequency" default 1, 
scalar "amplitude" default .5 ) 
end declare 


Figure 17.7: Shader declaration of displace_wave (p.528) 


By using the lambert shader for the material, we can see the displacement shader’s change to the 
geometry of the surface. 


material "wave" 


"lambert" ( 
"diffuse" 11 1, 
lights” ["lignt inet") ) 


displace "displace wave" ( 
"frequency" 3, 
"amplitude" .03 ) 
end material 


Figure 17.8: Displacement based on the world space coordinates of a polygon 


Displacement shaders use the same function signature as shaders returning a color in their result 
pointer, but define result as a pointer to miScalar. 
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struct displace wave { 
miScalar frequency; 
miScalar amplitude; 


hi 


miBoolean displace wave ( 
miScalar *result, miState *state, struct displace wave *params ) 


*result += miaux_sinusoid(state->point.x, 
*mi_eval_ scalar (&params->frequency) , 
*mi_eval_ scalar (&params->amplitude) ) ; 
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return miTRUE; 
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Figure 17.9: Shader source of displace_wave (p.528) 


The x component of state->point is used in line 9 as the input to miaux_sinusoid, with 
shader parameters used in lines 10-11 for the frequency and amplitude. Notice the use of += 
in line 9—this allows the result value of this displacement shader to accumulate in a shader 
list. 


This shader isn’t very useful, however, since the displacement is dependent on world coordinates 
(state->point )—if the object moves, the wave pattern would move also. How can we “fix” the 
wave pattern to the surface of the object? 


17.2.1 Using texture coordinates 


In shader displace_wave, we used state->point.x as input to miaux_sinusoid, making the 
displacement value dependent upon the position of the square in space. 


If an object has texture (uv) coordinates (for example, as defined by the modeling software that 
created the object), we can use those uv coordinates to calculate the value that will modify the 
surface normal. Any change to the surface will therefore be independent of the object’s position 
In space. 


We saw the wv coordinate space on an object in Chapter 9, in which we used the vector stored in 
state->tex_list [0]. We’ll add separated control for the amplitude and frequency in both the 
uv and v directions as arguments to create a more complex version of our last shader. We'll call 
this shader displace_wave_uv. 


declare shader 
scalar "displace wave_uv" ( 
scalar "frequency u”" default 


scalar "amplitude_u" default 

scalar "frequency v" default 

scalar "amplitude _v" default 
end declare 


Figure 17.10: Shader declaration of displace_wave_uv (p.528) 


The square polygon we’ll use for the material that includes displace_wave_uv ranges from 0.0 to 
1.0 in both uw and v, so the frequency_u and frequency_v parameters define how many periods 
of the sinusoid displace the square. 
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material "wave_uv" 
"lambert™ { 
"aA, ttuse” 11 1, 
 lighte” ("light inse%t 3 
displace "displace wave_uv" ( 


"frequency u" 3, 

"amplitude u" .02, 

"frequency v" 5, 

"amplitude v" .04 ) 
end material 


Figure 17.11: Displacement based on the texture space coordinates of a polygon 


The input to miaux_sinusoid is now the x and y coordinates of state->tex_list [0]. 


struct displace wave _uv { 
miScalar frequency _u; 
miScalar amplitude _ u; 
miScalar frequency v; 
miScalar amplitude v; 
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miBoolean displace wave_uv ( 
miScalar *result, miState *state, struct displace wave_uv *params ) 


*result += 
miaux sinusoid (state->tex list 
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*mi eval scalar ee >frequency v), 
*mi_ eval scalar(&params->amplitude_ v)) ; 
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return miTRUE; 
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Figure 17.12: Shader source of displace_wave_uv (p.528) 


The miaux_sinusoid function is called twice in lines 12-17 with the sum of the resulting values 
added to the result pointer to create the displacement. 


Circular ripple patterns can also be created with miaux_sinusoid by further modifying the 
texture coordinate input value. 


declare shader 
scalar "displace ripple" ( 
vector "center" default .5 .5 0, 


scalar "frequency" default 1, 
scalar "amplitude" default .1 ) 
end declare 


Figure 17.13: Shader declaration of displace_ripple (p.529) 
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material "ripple" 
"lambert" ( 
So. cluse" 1.1 i, 
wiaghra”™ (["laght inst"). ; 
displace 


"displace ripple" ( 
"‘“Ssencer” 23 «5. 0, 
"frequency" 16, 
"amplitude" .005 ) 
end material 


Figure 17.14: Circular ripples defined by the distance from a texture coordinate position in a polygon 


The center of the ripple pattern is passed as an argument of type miVector, though we are 
only using the x and y components for the ripple center in two-dimensional texture coordinate 
space. 


struct displace ripple { 
miVector center; 
miScalar frequency; 
miScalar amplitude; 


he 


miBoolean displace ripple ( 
miScalar *result, miState *state, struct displace ripple *params ) 


*result += miaux_sinusoid(mi_vector dist (mi_eval_ vector (&params->center) , 
&state->tex list[0]), 
*mi_eval_ scalar (&params->frequency) , 
*mi_eval_ scalar (&params->amplitude) ) ; 
return miTRUE; 
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Figure 17.15: Shader source of displace_ripple (p.529) 


17.3. Shader lists and displacement mapping 


In each of the displacement shaders, we have added the shader’s displacement calculation to the 

Prog 68, 2.3. Shader Lists value of the result pointer. This allows us to use these shaders in a shader list in the material. 
Each shader after the shader type statement (for example, displace) is considered to be a member 
of the list of shaders for that type. The list ends when the material ends or when another shader 
type statement is present. 
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Material "three ripples" 
"lambert" ( 
"diffuse" 11 1, 
ttaghte” (["laght angst") 
displace 
“displace ripple” ( 
“Senter” .2 .5 0, 
"frequency" 12, 
"amplitude" .005 ) 
"displace ripple" ( 
"Center" .8 .8 O, 
"frequency" 10, 
"amplitude" .005 ) 
"displace ripple" ( 
"Center" .8 .2 0, 
"frequency" 8, 
"amplitude" .005 ) 
end material 


Figure 17.16: List of three displacement shaders 


Lists of shaders support the implementation of shaders that control the displacement at different 
levels of detail. By separating the displacement calculation in this way, materials for distant objects 
could use only the large-scale displacements, since the visual effect of the smaller displacements 
would not be worth the increase in the geometric complexity of the object. 


material "waves with three ripples" 
"lambert" ( 
"diffuse" 111, 
rlagnts" ("light ingt"] } 
displace 

"displace wave" ( 
"frequency" 3, 
"amplitude" .03 ) 

"displace ripple" ( 
"center" .2 .5 Q, 
"frequency" 20, 
"amplitude" .003 ) 

"displace ripple" ( 
"Center" .8 .8 O, 
"frequency" 10, 
"amplitude" .005 ) 

"displace ripple" ( 
 Sencler”).Br.2 GO; 
"frequency" 8, 
"amplitude" .005 ) 

end material 


Figure 17.17: Displacement shaders with different levels of detail 


17.4. Using texture images to control displacement mapping 


Not all the surface irregularities we'd like to render will have a mathematical representation. In 

the same way that we can use digital images as texture maps to define a complex color scheme Prog 17, 1.12. Texture 
for a surface, it also would be very useful to define the small-scale geometric detail of the surface oe eae 
with a digital image. If we think of the intensity of the image as representing the height of the 

surface, we can construct images that represent complex surface irregularities that would be very 

difficult to define mathematically. 
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We’ll specify the texture as a parameter to the shader. Since the texture values will be in the range 
of 0.0 to 1.0, we'll also specify a scaling factor. 


declare shader 
scalar "displace texture" ( 


color texture "texture", 
scalar "factor" default .1 ) 
end declare 


Figure 17.18: Shader declaration of displace_texture (p.530) 


Knowing that the pixel values of the texture image will be treated as distances, we can create 
images with this in mind. For example, the image in Figure 17.19 uses the sine function to control 
the intensity of pixels based on the distance to the center to create a spherical displacement. 


Figure 17.19: An image for use as a displacement map 


Prog 112, 2.7.3. Textures The color texture is defined and passed to the texture argument to shader displace_texture. 


color texture "bubbles" "bubbles.tif" 


material "bubble" 
"lambert" ( 
aittuse” 1 1 1, 


"lights" ["light inst") ) 
displace "displace texture" ( 
"texture" "bubbles", 
"factor" .05 ) 
end material 


Figure 17.20: Texture map samples as displacement values 


The structure of displace_texture is the same as the previous shaders even though we are using 
a texture map to calculate the displacement amount. 
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struct displace texture { 
miTag texture; 
miScalar factor; 


}3 


miBoolean displace texture ( 
miScalar *result, miState *state, struct displace texture *params) 


1 
2 
3 
a 
5 
6 
7 
8 


miColor color; 
mi lookup color texture(&color, state, 
*mi eval tag(&params->texture) , 
&state->tex list([0]); 
*result += *mi_eval scalar(&params->factor) * color.r; 
return miTRUE; 


Figure 17.21: Shader source of displace_texture (p.530) 


In this shader, we assume that the texture value to be used is stored in the red channel, so in 
line 13 we multiply the scaling factor parameter by color.r. We could have used a color image 
for the texture, and then averaged the channels to generate a single value, but we have defined the 
scalar value explicitly in this case. 


17.5 Combining displacement mapping with color 


So far, we’ve limited the material shader to the simple lighting effect of lambert. However, we 
can use any material shader in conjunction with a displacement shader. To simulate a natural 
material like wood, we can derive a texture input for the material and displacement shaders from 
the same source image. 


Rendering using just a lambert shader with a wood texture produces a surface without any 
apparent geometric detail. 


shader "wood color" 
"texture uv" ( 
"tex "good color texture” 


material "wood" 
"lambert" ( 
"diffuse" = "wood_color", 
Wiighte” ("light anse™] ) 
end material 


Figure 17.22: Wood texture map on a polygon 


However, we can use the wood texture map to create a second texture map to be used for 
displacements. 
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Figure 17.23: The original wood image for color and the processed version for use in displacement 


Since darker parts of wood grain are associated with harder parts of the wood, older wood 
may show characteristic three-dimensional patterns of wear that relate the grain to the surface 
geometry of the wood. By constructing a texture for the displacement map that inverts a 
monochrome version of the color image, we can associate darker parts of the grain with larger 
values of displacement—harder parts of the wood that aren’t as eroded. 


color texture "wood_color_ texture" 
"wood color.tif" 


color texture "wood displace texture" 
"wood bump.tif" 


shader "wood color" 
"texture uv" ( 
"tex" “wood color texture" } 


material "wood displace" 
"lambert" ( 
"diffuse" = "wood color", 
‘ieee ["Zaght inet), } 
displace 
"displace texture" ( 
"texture" "wood displace texture", 
tfacror"® .02 } 
end material 


Figure 17.24: Texture maps defining both color and displacement for a polygon 


The wood_displace material is a good example of two different types of texture map use. To 
use a texture map for the diffuse parameter of the lambert shader, we need to define a shader, 
wood_color in this case, and then use shader assignment with the equals sign (=) to provide that 
shader as the value of the diffuse parameter. The displace_texture shader, on the other hand, 
takes acolor texture as an argument, so the wood_displace_texture is used as the parameter 
value directly. 


This example also hints at possible organizational techniques for dealing with texture maps in 
production. The processing of a color image into a gray-scale representation and then inverting it 
could have been calculated in the shader, but creating separate texture map images may serve the 
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design and approval requirements of a production pipeline. There will also be some efficiency 
benefit if a given scene is rendered many times and the modification of a texture image has already 
been pre-computed and stored in a secondary texture file. 


17.6 Using noise functions with displacement mapping 


The simulation of wood in the last section depended upon texture maps for color and 

displacement. Noise functions can also be used for displacement values. In particular, functions Prog 359, 3.26.8. Noise 
like the miaux_summed_noise function in Section 9.7 can simulate a variety of structures in nature. sani 

In that section, the shader defined miColor values. For displacement, we need to provide values 

of type miScalar, the result type of shader summed_noise_scalar. 


declare shader 
scalar "summed_noise scalar" ( 
scalar "point scale" default 1, 
scalar "magnitude" default 1, 


scalar "octave_scaling" default 2, 

scalar "summing weight" default 2, 

integer "number _of octaves" default 5 ) 
end declare 


Figure 17.25: Shader declaration of summed_noise_scalar (p.530) 


Shader assignment can also be used for displacement shaders with the equals sign (=) Prog66, 2.2. Shader 
syntax Definitions 


shader "land_displacement" 

"summed noise scalar" ( 
"point sacale" 10, 
"magnitude" .05 ) 


material "water" 
"transparent" ( 
Yeplor’ 7 0 1, 
"transparency" .3 .3 .3 ) 
end material 


material "land" 


"lambert" ( 
"diffuse" eo a ots 
‘iignte”" ["1agne inec") 
displace 


= "land displacement" 
end material 


Figure 17.26: Displacement around zero as shown by object interpenetration 


A transparent polygon in the zero plane of the y axis demonstrates that the summed_noise_scalar 
function creates noise values around 0.0. 


258 17. Modifying surface geometry 


struct summed_noise scalar { 
miScalar point scale; 
miScalar magnitude; 
miScalar octave_scaling; 
miScalar summing weight; 
miInteger number of octaves; 


Pe 


miBoolean summed_noise scalar ( 
miScalar *result, miState *state, struct summed_noise scalar *params ) 


miVector object _point; 
miScalar magnitude = *mi_eval_scalar(&params->magnitude), noise sum; 
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mi point _to_object(state, &object point, &state->point) ; 
mi_vector mul (&object_ point, *mi_eval_scalar(&params->point_ scale) ) ; 


noise sum = miaux_summed_noise(&object point, 
*mi_eval_ scalar (&params->summing_ weight), 
*mi_eval_ scalar (&params->octave_scaling), 
*mi_eval_ integer (&params->number of octaves) ); 


*result += miaux_fit(noise sum, 0.0, 1.0, -magnitude, magnitude) ; 


return miTRUE; 
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Figure 17.27: Shader source of summed_noise_scalar (p.530) 


The result of miaux_summed_noise in line 18 is in the range of 0.0 to 1.0. The call to miaux_fit 
in line 23 scales the noise value around zero by an amount defined by the input parameter 
magnitude. 


Chapter 18 


Modifying surface orientation 


In the last chapter, we used displacement shaders to modify the surface geometry, with the normals 

adjusted by mental ray to account for the new orientation of the surface. In this chapter, we’ll 

look at a technique that doesn’t change the geometry of the surface as we did with displacement 

mapping, but only modifies the normal’s description of the surface’s orientation. Because we can 

use this technique to map a set of orientation changes to the surface, and these changes can create 

a bumpy look to the surface, this technique has traditionally been called bump mapping—we are Rend 85, 4.4. Bump Mapping 
creating a mapping from positions on the surface to a change of the apparent orientation at that 

point. 


18.1 Simulating surface orientation 


For bump mapping, points on a surface are associated with corresponding points on the surface 
to be simulated. The bump mapping shader calculates the normals of the simulated surface to Prog 242, 3.8. Material 
use for the normals of the original surface. saa 


Figure 18.1: Associating points on a surface with a surface geometry to be simulated 


You can create the appearance of this simulated surface by modifying, or perturbing, the normal 
vectors of a flat surface to the orientation of the simulated surface, even though the actual surface 
is not in fact oriented in those directions. 


[|| /1\\ 


Figure 18.2: Changing the normals of a flat surface to simulate geometric complexity 


Prog 68, 2.3. Shader Lists 
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By using the direction of the vectors in Figure 18.1 fora flat surface, the rendered image will appear 
to have its geometric shape, even though it is geometrically flat. Because additional geometric 
data is not created, bump mapping is an efficient alternative to displacement mapping when the 
actual geometric modification of the surface is not required, as for objects at a distance. 


18.2. Modifying the normal in a shader 


For the shaders that used lights to calculate surface in Chapter 12, the orientation of the surface 
is determined by the vector passed to the shaders in the state variable, state->normal. In our 
bump mapping shaders, we’ll change the value of this vector in order to modify the typical value 
that would be calculated by the shaders. 


How can we modify the state->normal vector before the color calculations made by the primary 
shader in the material? We can use the mechanism of a shader list as we did with displacements 
in the last chapter. The bump mapping shader will be called first, and rather than modifying the 
color being calculated (in the result parameter), it will modify state->normal instead. 


For our bump mapping shaders, we’ll use the same polygon with a lambert shader in its material 
as we did with displacements. 


material "lambert" 
"lambert" ( 


"diffuse" 1114, 
niighnts™ {(*1light inst") ) 
end material 


Figure 18.3: Simple scene for bump mapping shader examples 


By including a bump mapping shader along with the lambert material shader, we can modify 
the surface orientation. Notice that shader bump_wave occurs before the lambert shader which 
defines the surface color. For all shader lists, the shaders are executed in the order defined by the 
list. 


material "wave" 
"bump wave" ( 
"frequency" 3, 
"amplitude" .4 ) 


"lambert" ( 
"diffuse" 111, 
"isgnte”" {"laght inst™] ) 
end material 


Figure 18.4: Modifying the apparent surface orientation by changing the x component of its normal 


Our bump mapping shaders will use the miaux_sinusoid function as we did for displace- 
ments. 
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1 double miaux_sinusoid(double v, double frequency, double amplitude) 
2 4 
3 
4 


return sin(v * frequency * M PI * 2.0) * amplitude; 


} 


Figure 18.5: Function miaux_sinusoid 


The arguments to the sinusoid function are passed as arguments to a shader that we'll call 
bump-_wave. 


declare shader 
color "bump wave" ( 
scalar "frequency" default 1, 
scalar "amplitude" default .5 ) 
end declare 


Figure 18.6: Shader declaration of bump_wave (p.531) 


The parameters to bump_wave are identical to displace_wave and used in miaux_sinusoid in the 
same way. 


struct bump _wave { 
miScalar frequency; 
miScalar amplitude; 


}a 


miBoolean bump_wave ( 
miColor *result, miState *state, struct bump wave *params ) 


state->normal.x += miaux_sSinusoid(state->point.x, 
*mi_eval_ scalar (&params->frequency) , 
*mi_eval_scalar(&params->amplitude) ) ; 
mi vector normalize (&state->normal) ; 
return miTRUE; 
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Figure 18.7: Shader source of bump_wave (p.531) 


The x component of the state->normal vector is modified in lines 9-11 based on the x coordinate Prog 209, 3.4.4. Intersection 


of the current point, and the vector re-normalized with mi_vector_normalize in line 12. Prog 349, 3.26.7. Math 
Functions 


18.3 Changing the normal based on texture coordinates 


As we did with displacements, we can associate bump mapping with the texture coordinates of 
the object. Shader displace_wave_uv provides separate frequency and amplitude control for the 
texture coordinates through the shader parameters. 
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declare shader 
color "bump _wave_uv" ( 
scalar "frequency u" default 


scalar "amplitude _u" default 

scalar "frequency v" default 

scalar "amplitude v" default 
end declare 


Figure 18.8: Shader declaration of bump_wave_uv (p.532) 


We'll use uw and v as arguments to function sinusoid, and then modify the x and y components 
of the normal vector separately. 


miScalar 
miScalar 
miScalar 
miScalar 


bi 
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state->normal.x += miaux_sinusoid(state->tex_list 


state->normal.y += miaux_sinusoid(state->tex list 


struct bump wave _uv { 


frequency u; 
amplitude _u; 
frequency v; 
amplitude v; 


miBoolean bump _wave_uv ( 
miColor *result, miState *state, struct bump wave _uv *params ) 


[0]. 
bok aie Boies tees >frequency _ 
wake ce ee >amplitude _ 
[0]. 
Rd, mya coated we >frequency _ 
*mi_eval_ scalar (&params->amplitude _ 


mi_vector_ normalize (&state->normal) ; 
return miTRUE; 


Figure 18.9: Shader source of bump_wave_uv (p.532) 
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When we render the same square with the bump_wave_uv shader, the separate modifications 
to the components of the normal, state->normal.x and state->normal.y, create 


pattern. 


material "wave_uv" 
"bump _wave_uv" ( 
"Erequency uw" 
"amplitude u" 
"frequency v" 


"amplitude v" 
"lambert" ( 
"aittuee”™ Lt i, 
nTagnes*— ("light inst") 
end material 


Figure 18.10: Modifying both the x and y components of the surface normal 


a grid 


) 
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18.4 Evaluating a function in the sample neighborhood 


By using the uv coordinates in the sinusoid function, the modification of the surface normals 
now have a fixed relationship to the surface of the object. However, we will not always be able 
to depend upon objects that are as conveniently uniform as our square is with its simple texture 
coordinate space. We also took advantage of the fact that the surface normals of the square all 
pointed up—they were all vectors of 0 10 in which we could modify its x and y components with 
(relatively) predictable results. 


We can instead consider the sinusoid function to define the relative height of the surface at each 
rendered point. We can then think about the “shape” defined by our sinusoid function. By 
examining nearby values of the function and comparing them to our original value, we can then 
determine the orientation of the sinusoid shape at that point. 


But what do we use to calculate “nearby values” for our sinusoid function? The texture 
coordinates define a space on the surface of the object, and objects may also optionally define 
vectors for increasing u and v in texture space, the bump basis vectors. We can use these vectors to 
“bend” the surface normal in the direction of the greatest difference in the function’s values. 


normal vector 


uv=[o,1] uv=[1,0] 


v basis vector 


u basis vector 


uv=[0,0| uv=[1,0| 


Figure 18.11: The normal vector and the two bump basis vectors 


Rather than making linear waves, shader bump_ripple defines a center point and creates circular 
waves radiating out from there. To use the bump basis vectors, we calculate the sinusoid 
function three times: once at the current point, and then “over” and “up” (in texture space) by a 
small amount. This tells us how the sinusoid function is changing at that point by calculating the 
two differences from the original point. We can scale the bump basis vectors by that difference. 
Multiplying the normal vector by those scaled bump basis vectors “bends” the surface normal in 
a direction that corresponds to the changing values of the sinusoid function. 


We also need to be more careful about how we treat state->normal. In the last two shaders, 
we manipulated state->normal directly, making an implicit assumption that the normal vector 
in the state correspond to our intuitive perception of the surface. However, mental ray uses 
a coordinate system called internal space for its calculations. In our shader, we will need to 
use one of the coordinate space functions to transform state->normal to object space and back 
again. 


The center is passed as an argument to the bump_ripple shader: 


Prog 211, 3.4.5. Textures, 
Motion, Derivatives 


Prog 190, 3.2. Coordinate 
Systems 
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declare shader 
color "bump ripple" ( 
vector "center" default .5 


scalar "frequency" default 1, 

scalar "amplitude" default 

scalar "nearby" default 
end declare 


Figure 18.12: Shader declaration of bump_ripple (p.532) 


Like the previous bump mapping materials, the bump_ripple shader occurs before the lambert 


shader: 


material "ripple" 
"bump ripple" ( 
“Senter” 4.4 .5 OQ, 
"frequency" 16, 


"amplitude" .5, ) 
"lambert" ( 
"diffuse" 1114, 
Nlaghnte" ["laght inet") ) 
end material 


Figure 18.13: Modifying the normal based on the distance from a point as input to a sinusoidal function 


Shader bump_ripple uses several local variables to identify intermediate values in the bump- 
mapping process. 
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struct bump ripple { 
miVector center; 
miScalar frequency; 
miScalar amplitude; 
miScalar nearby; 


}; 


miBoolean bump ripple ( 


{ 
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miColor *result, miState *state, struct bump ripple *params ) 


double ripple here, ripple over, ripple up, 
change going over, change going up; 
miVector here, over, up; 


miVector center = *mi_eval_ vector (&params->center) ; 
miScalar frequency = *mi_eval_ scalar (&params->frequency) ; 
miScalar amplitude *mi_eval_ scalar (&params->amplitude) ; 
miScalar nearby = *mi_eval_ scalar (&params->nearby) ; 


miVector bump _basis_u = state->bump_ x list[0]; 
miVector bump basis v = state->bump y list[0]; 


here = state->tex_list[0]; 
miaux set _vector(&over, here.x + nearby, here.y, here.z) ; 
miaux_ set vector(&up, here.x, here.y + nearby, here.z); 


ripple here = miaux_sinusoid(mi_vector_dist(&center, &here), 
frequency, amplitude) ; 
ripple over = miaux_sinusoid(mi_vector_ dist(&center, &over), 
frequency, amplitude) ; 
ripple up = miaux_sinusoid(mi_vector_dist(&center, &up), 
frequency, amplitude) ; 


change going over = ripple over - ripple_here; 
change going up = ripple over - ripple up; 


mi vector mul(&bump basis _u, -change_ going over) ; 
mi vector mul(&bump_ basis v, -change_ going up) ; 


mi_vector_to_object(state, &state->normal, &state->normal) ; 
mi_vector_add(&state->normal, &state->normal, &bump_basis u); 
mi_vector_add(&state->normal, &state->normal, &bump_basis v) ; 
mi_vector_normalize(&state->normal) ; 

mi vector _from_object (state, &state->normal, &state->normal) ; 


return miTRUE; 


Figure 18.14: Shader source of bump_ripple (p.532) 


The calculation of the ripple surface orientation can be broken down into a series of 
operations: 


Lines 20-21 Make a copy of the bump basis vectors from the object. 

Lines 23-25 Copy the current point and calculate nearby points in texture space. 

Lines 27-32 Determine the value of the sinusoid function at the three points. 

Lines 34-35 Find the difference in the sinusoid function and the two nearby points. 

Lines 37-38 Scale the bump basis vectors based on the difference in the sinusoid function. 
Line 40 Transform state->normal to object space 

Lines 41-43 Modify the surface normal based on the scaled bump basis vectors; normalize. 
Line 44 Transform state->normal back to internal space 
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18.5 Shader lists and bump mapping 


The bump mapping shaders we have written modify the current value of the state->normal 
using a shader list that ends with lambert. We can include additional bump mapping shaders in 

Prog 68, 2.3. Shader Lists a shader list that also make modifications to state->normal before lambert calculates the color 
value based on the perturbed normal. 


material "three ripples" 
"bump ripple" ( 
MeaenLer”™' .2 «5 
"frequency" 12 
"bump ripple" ( 
"Senter" .8 .8 
"frequency" 10 


0, 
) 
0, 
) 
"bump ripple" ( 

"Center" .8 .2 0, 

"frequency" 8 ) 
"lambert" ( 

"diftfuse" 11 i, 


"lights" [{"light inet") 
material 


Figure 18.15: Three modifications to the surface normal in a shader list 


18.6 Using images to control bump mapping 


Using an image means that determining our “over” and “up” values requires that we sample the 
texture three times. Now the idea of “nearby” means “nearby in the texture image.” We also 
need to replace our control of the degree of surface change for which we used “amplitude” in our 
previous shader. We’ll call this parameter “factor” and the new shader bump_texture: 


declare shader 
color "bump texture" ( 
color texture "texture", 


scalar "factor" default 1, 
scalar "nearby" default .001 ) 
end declare 


Figure 18.16: Shader declaration of bump_texture (p.534) 


We’ll use the same texture for bump mapping as we did with displacements to better show the 
different result of the two techniques. 
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Figure 18.17: An image for use as a bump map 


If the geometric scale of the features to be simulated is small enough that the silhouettes of the 
objects and their mutual occlusion is not required, then bump mapping can be used instead of 
displacements. 


color texture "bubbles" "bubbles.tif" 


material "bubble texture" 
"bump .texture” . ( 
"texture" "bubbles", 


"Factor” .30 ) 
"lambert" ( 
tarttuse® 1.1.1, 
"laguees” ([Vlagnt inet” | 
end material 


Figure 18.18: Using the color values of a texture map to define surface orientation 


The shader now uses texture lookups for the manipulation of the bump basis vectors. 
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struct bump texture { 
miTag texture; 
miScalar factor; 
miScalar nearby; 


ra 


miBoolean bump texture ( 


{ 
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miColor *result, miState *state, struct bump texture *params ) 


miColor color_here, color_over, color_up; 
miScalar value_here, value_over, value_up, 

change going over, change going _ up; 
miVector here, over, up; 


miTag texture = *mi_eval_tag(&params->texture) ; 
miScalar factor = *mi_eval_scalar(&params->factor) ; 
miScalar nearby = *mi_eval_scalar(&params->nearby) ; 


miVector bump basis _ u state->bump_x list [0]; 
miVector bump basis v state->bump_ y list[0]; 


here = state->tex list[0]; 
miaux set vector(&over, here.x + nearby, here.y, here.z); 
miaux_ set vector(&up, here.x, here.y + nearby, here.z) ; 


if (!mi_lookup color texture(&color here, state, texture, &here) ) 
return miFALSE; 
value_here = miaux_color_channel average (&color_here) ; 


mi_flush_cache(state) ; 
value_over = mi_lookup_color_texture(&color_over, state, texture, &over) ? 
miaux_ color channel average (&color over) : value_here; 


mi_flush_cache (state) ; 
value_up = mi_lookup_ color texture(&color_up, state, texture, &up) ? 
miaux_color_ channel average (&color_up) : value_here; 


change going over = factor * (value_over - value_here) ; 
change going up = factor * (value_up - value here); 


mi_vector_mul(&bump_basis_u, -change_ going over) ; 
mi vector mul(&bump basis v, -change_going_up) ; 


mi vector to object(state, &state->normal, &state->normal) ; 
mi vector add(&state->normal, &state->normal, &bump_ basis _u); 
mi vector _add(&state->normal, &state->normal, &bump_basis v) ; 
mi_vector_ normalize (&state->normal) ; 

mi vector from_object(state, &state->normal, &state->normal) ; 


return miTRUE; 


Figure 18.19: Shader source of bump_texture (p.534) 


The changes from the previous shader use texture map samples for the bump mapping 
values: 


Lines 26-28 Get the texture value at the current uw and v coordinates. As before, the value of 
local variable here is copied from state->tex_list [0] in line 22. 


Lines 30-32 Get the value of the nearby texture map sample in the uw direction. The caching of 
texture values must be disabled to get a new value. 


Lines 34-36 Get the value of the nearby texture map sample in the v direction, also disabling the 
texture cache. 
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18.7. Combining bump mapping with color 


Texture maps made for displacement mapping can also be used for bump mapping. We’ll use the 
same textures for wood as we did in the last chapter. 


Figure 18.20: The original wood image for color mapping and its negative for bump mapping 


The resulting image does not have the geometric detail of the displacement version, but for 
the typical scale of wood grain, bump mapping alone may be sufficient to convey the desired 
visual impression, and without the increase in geometric complexity required by displacement 


mapping. 


color texture "wood_color" 
"wood texture.tif" 


material "wood_bump_ texture" 
"bump texture" ( 
"Cexture" "wood_bump", 


"factor" 10 ) 
"blinmn"™ { 
"specular" .3 .3 «3; 
"diffuse" = "wood shader", 
“iighnte™ ["“laght ingt™] ) 
end material 


Figure 18.21: Using a single image as the source for both color and bump-mapping information 
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Chapter 19 


Creating geometric objects 


So far, all of our mental ray API library functions have come from the library declared in 
the header file shader .h, like the illumination model functions in Chapter 12 to calculate the 
specular component—mi_phong_specular, mi_blinn_specular, and friends. Shaders can also 
call functions in mental ray’s geometry shader API, declared in geoshader.h. These functions 
mirror the language of the mi scene file, and can be used to define geometry shaders that create 
geometric data. Like displacement shaders, the role of the geometry shader isn’t to “shade.” 
Geometry shaders add elements to the geometric component of the scene database constructed 
by mental ray before the actual rendering begins. Some objects lend themselves to procedural 
construction, either because they are based on pre-existing data (CAD data that is translated 
into mental ray’s object representation) or because they use quasi-random techniques to model 
natural phenomena, like plants and trees. 


Given the capabilities of geometry shaders, we’ll also explore how we can delay the creation of 
geometry until it is actually required during rendering with placeholder objects. This technique 
is especially useful for the geometric complexity required in modeling natural phenomena like 
plants in a procedural manner. In the next chapter, we’ll explore the use of placeholder objects 
to create objects containing a very large number of mental ray’s hair primitives 


19.1 Creating a square polygon 


The relationship between the .mi scene file and the geometry shader API can be demonstrated 
by showing the correspondence between an object created in a scene file and by the API. We’ll 
use API functions to create polygon objects, but higher-order geometric representations—tfree- 
form and hierarchical subdivision surfaces—will be constructed through the API in a similar 
manner. 


To create a single-polygon object in mental ray, we minimally need to perform these 
actions: 


1. Begin the object definition. 

Set the options. 

Begin the object group definition. 

Define the vectors to be used for vertices. 
Define the vectors to be used for normals. 


ee oe 


Define the vectors to be used for texture coordinates. 
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7. Specify the sets of vectors to be used for the position, normal and texture coordinates of 
each vertex. 


8. Specify the vertices to be used for each polygon. 
9. End the object group definition. 

10. End the object definition. 

11. Add the resulting object to the database. 


A scene file fragment that implements these steps is shown in Figure 19.1. Note that the vectors 
defined in steps 4 through 6 are referenced to construct vertices in step 7 by the indices implied 
by their order in the file, beginning with 0. Similarly, the vertices defined in step 7 are referenced 
to construct a polygon in step 8 by their implied indices. 


# 1. Begin the object definition. 
object "Square-object" 


# 2. Set the object flags. 
visible on 
shadow 3 


# 3. Begin the object group definition. 
group 
ca 


Define the vectors to be used for vertices. 
-.5 0 


4 
S 
<2 
5 
=" 


-.5 0 

5 O 

.5s 0 

Define the vectors to be used for 
+ 


Define the vectors to be used for UV coordinates. 


Specify the sets of vectors to be used for the position, 
normal and texture coordinates of each vertex. 
= £ 3 


Specify the vertices to be used for each polygon. 
oO 1i-2 3 


# 9. End the object group definition. 
end group 


# 10. End the object definition. 
end object 


Figure 19.1: An object defined by a .mi file 


The names of functions in the API that implement scene file statements begin with mi_api. 
For some scene file statements, the corresponding API function names are easily recognized, for 
example, the API function mi_api_object_endforend object. However, the implicit definition 
of vectors in steps 4 through 6 are implemented with explicit functions in the API. Figure 19.2 
lists a few of the basic geometry API functions. 
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Scene file Geometry shader API 


Objects object mame mi_api_object_begin 
end object mi_api_object_end 


Object groups group mi_api_object_group_begin 
end group mi_api_object_group_end 
Vectors implied mi_api_vector_xyz_add 
Vertex data v index mi_api_vertex_add 
n index mi_api_vertex_normal_add 
t index mi_api_vertex_tex_add 
Polygons Pp mi_api_poly_begin_tag 
implied mi_api_poly_index_add 
implied mi_api_poly_end 
Database implied mi_geoshader_add_result 


Figure 19.2: Basic geometry API functions 


What defines this correspondence between scene file statements and the functions of the API 
library? In Chapter 2, I talked about the structure of a scene file in an informal way, dividing the 
file into “blocks” that defined objects, lights, and cameras. However, a formal definition of scene 
file structure is used by mental ray when it reads the scene file before the actual rendering can be 
begin. 


When mental ray reads a scene file as input, it interprets, or parses, the text of the scene file 

based on a set of pattern rules. These rules are defined in a language used by a program called 

yacc to generate the C code that implements the parsing process. These rules are included as an 

appendix in the Programming mental ray manual and as part of the on-line manual distributed Prog 739, B. Scene File 
with the mental ray software. With these rules, you have an unambiguous description of what iets 

API functions are called during the parsing of the scene file. 


Even without a full understanding of the yacc rule syntax, we can get an idea of how the various 

elements in the scene file are implemented using the API library. For example, Figure 19.3 is the 

yacc rule for the object element ina scene file. The rule defines a pattern in the scene file; when Prog 124, 2.7.8. Objects 
the pattern is found, the API functions specified in the rule are executed. 


: OBJECT opt_symbol 
{ curr_obj = mi_api_object_begin($2); } 
obj flags 


object _body 
END OBJECT 
{ mi_api_ object _end(); } 


Figure 19.3: Rule in the yacc grammar for the object element 


Typically in yacc, lowercase words represent rules. Uppercase words are symbolic names for 
words in the language that yacc is parsing. In this case, OBJECT and END represent the words 
object and end in the scene file. Functions to be executed during parsing are enclosed in curly 
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braces, as in C. The colon character on the first line after the symbol object means that what 
follows is the rule for object, with the end of the rule signaled by the semicolon character. The 
symbols obj-flags and obj_body are rules defined later that further specify the syntax of an 
object element in the scene file. 


Using the functions in Figure 19.2 we can write a geometry shader that duplicates the scene file 
in Figure 19.1. The arguments of this shader are the same as we have seen: the result, the state, 
and the parameters. The result in this case is used as an argument to the function that adds our 
new object to the scene database, mi_geoshader_add_result. 


19.1 Creating a square polygon 


miBoolean square ( 


{ 


In line 9, a pointer of type mi0bject is set to the return value of mi_api_object_begin. Weare Prog526, 4.3.9. Objects 
Prog 391, 3.26.17. Memory 


miTag *result, miState *state, void *params) 


yh a 
miVector v; 
miTag object tag; 


/* 1. Begin the object definition. */ 
miObject *obj = mi_api_ object begin(mi_mem_strdup("::square") ); 


/* 2. Set the object flags. */ 
obj->visible = miTRUE; 
obj->shadow = 3; 


/* 3. Begin the object group definition. */ 
il api object group _begin(0.0); 


/* 4. Define the vectors to be used for vertices. */ 

Vv -.57 v.y = -.5; v.z = 0; mi_apl vector xyz_add(&v) ; 
v.x = .5; mi_api_ vector xyz _ add(&v) ; 

Vv .5; mi_api_vector_ xyz add(&v) ; 

Vv -.5; mi_api_ vector _ xyz add(&v) ; 


/* 5. Define the vectors to be used for normals. */ 
v.x = 0; v.y = 0; v.z = 1; mi_api_vector_xyz_add(&v) ; 


Define the vectors to be used for texture coordinates. */ 
O; v.y = 0; v.z = 0; mi_api_vector_xyz_ add(&v); 
= 1; mi_api_ vector xyz add(&v) ; 
= 1; mi_api_vector_ xyz add(&v) ; 
0; mi_api_vector_ xyz _ add(&v); 


Specify the sets of vectors to be used for the position, 
normal and coordinates of each vertex. */ 
for (i = 0; i < 4; i++) { 
mi.api vertex_add(i) ; 
mi api vertex normal_add(4) ; 
mi_api_vertex_tex_add(i + 5, - =1) ; 


} 


/* 8. Specify the vertices to be used for each polygon. */ 
mi api poly begin _tag(1, 0); 
for (1 = 0; 1 < 4; i++) 
mi_api_ poly index _add(i)j; 
mi_api_poly _end(); 


/* 9. End the object group definition. */ 
mi api object group end(); 


/* 10. End the object definition. */ 
object _tag = mi_api_object_end(); 


/* 11. Add the resulting object to the database. */ 
return mi_geoshader_add_result(result, object_tag) ; 


Figure 19.4: Shader source of square (p.535) 
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specifying the name of the object as a literal C string, which requires the use of mi_mem_strdup to 
allocate memory and copy the literal character array to it. Function mi_api_object_begin uses 
this allocated block of memory to name the object and releases it when it is done. 


Prog 74, 2.6. Commands 


Prog 453, 4.2.1. Symbol 
Tables 
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Each object name in the scene database is contained within a group of names called a namespace. 
The two colon characters (::) separate the namespace from the name. Using namespaces, we can 
divide a scene into separate parts with the same names, but avoid ambiguity if we use the same 
name in more than one part. This would allow complex models constructed in a procedural 
way (translated from some other data format, for example), to employ names that represent their 
original hierarchical structure. 


In our square shader, we have defined the object to be in the global namespace in line 9 by 
explicitly using the “::” prefix without a string for the namespace. Without the “::” prefix, 
mental ray will create a unique namespace identifier for the object. (You will see the name of the 
object printed during scene parsing when the verbose message level is 6 and above.) 


In lines 12-13 we use the object pointer created in line 9 to define the value of the object flags. 
Visibility is either on or off (type miBoolean), but note that the shadow flag is set to 3. Some 
flags specify four values, the combinations of casting and receiving—neither, both, or either one 
or the other. 


Mode Flag value 


No effect 0 
Casts 1 
Receives 2 
Both 3 


Figure 19.5: Shadow modes 


The miVector variable v declared in line 5 is reused in lines 19-31 to define the vector for vertices, 
the normal of the polygon, and the texture coordinates. As in the .mi file version, the index of 
these vectors is defined by the order of their definition, and these implied indices are used in 
lines 35-39 as the four vertices are defined. Because this shader defines a single square, the loops 
in lines 35-39 and lines 43-44 make use of explicit numeric values—typically considered to be 
bad C programming style. As we’ll see in the next section, a procedural approach to geometry 
shader construction can allow for more flexibility as well as producing code that is easier to 


debug. 


The API functions in lines 48-54 are typical for a geometry shader. Note that the result 
argument to the shader is used as the first argument to mi_geoshader_add_result. The separate 
assignment to the object_tag variable is included in this shader for clarity; a more typical 
geometry shader might use the call to mi_api_object_end in line 51 as the second argument to 
mi_geoshader_add_result. 


Even though all this is quite different from what we’ve seen in the previous shader types, the 
declaration of a geometry shader has the same syntax as a material shader defining a color, but 
returns a value of type geometry. 


declare shader 


geometry "Square" () 
end declare 


Figure 19.6: Shader declaration of square (p.535) 
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In the object instance, the call to the geometry shader replaces the name of a previously defined 
object element. In Figure 19.7, the position of an object name, after the instance name (here 
square-instance) is occupied by the call to geometry shader square. The keyword geometry 
tells the mental ray parser that what follows is a geometry shader call, and not the name of a 
previously defined object in the scene database. 


material "diffuse" 
"lambert" ( 
"lignte” ["light-inst"] ) 
end material 


instance "square-instance" 
geometry "Square" () 
material "diffuse" 
transform 


0 
0 
0 
0 


Figure 19.7: Geometry shader square used in object instance 


For simplicity, our square shader does not use any arguments in its construction of geometry. 
In the next section, we’ll define a parameter struct for a geometry shader in the same way that we 
have for material shaders. 


19.2 Procedural use of the geometry API 


For the definition of a single polygon like our square shader, the complexity of a geometry 
shader hardly makes it a better way to create geometry than an object defined in the .mi file. 
Even the conversion of complex object data from some other format may best be implemented 
as a translation from the original data to an object in scene file format. However, if the object has 
a procedural geometric definition, then we can use the flexibility of the geometry shader to our 
advantage. 


Our next geometry shader will create a set of triangles of random size distributed within a distance 
from a given point. We’re using randomness here as an easy way to generate a lot of variable 
data. (Later in the chapter we’ll more carefully parameterize how we use a series of random 
numbers.) 


Prog 359, 3.26.8. Noise 
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material "amb_occlude" 
"ambient _occlusion_cutoff" ( 
"Samples" 200, 
"ento£fft distance” 9 ) 
end material 


instance "triangles-instance" 
geometry "triangles" ( 
"Count" 1000, 


"phox tin" -.5 -.5 =-.5, 

"bbox max" .5 .9 .5, 

"edge length max" .5 ) 
material "amb _occlude" 
transform 


end instance 


Figure 19.8: Procedural geometric construction rendered with ambient occlusion 


The API library provides a set of functions for random number generation. Function mi_random 
returns values in the range 0.0 to 1.0 (excluding 1.0). Since we will frequently want to create 
random numbers within a given range, we’ll define an auxiliary function miaux_random_range 
to fit the result of mi_random within a given minimum and maximum value. 


1 float miaux_random_range(float min_value, float max_value) 
2 { 
3 
4 


} 


return miaux_fit(mi_random(), 0.0, 1.0, min_value, max_value) ; 


Figure 19.9: Function miaux_random_range 


In material shaders, we are writing code that is typically run for every sample in during rendering, 
potentially millions of times. But since geometry shaders run only once, we can be a little less 
cautious about inefficiency in our code. For example, to pick a random point within a sphere, we 
can easily pick a random point within the cube that surrounds that sphere, and then test to see 
whether its distance from the center is less than the sphere’s radius. Since a sphere is larger than 
half the cube that contains it, such a function will on average need to pick less than two points 
to find a containing point. Not something we would want to do at the sample level in a material 
shader, but the simplicity of implementation makes it a good first implementation for a geometry 


shader. 


void miaux_random_point_in_unit_sphere(float *x, float *y, float *z) 


do { 
*x = miaux_random_range(-.5, 


*Z miaux_random_range(-.5, ‘ 


1 

Ps 

3 

4 

5 *y = miaux_ random _range(-.5, 

6 

7 } while (sqrt((*x * *x) +(*y * *y) 
8 


} 


Figure 19.10: Function miaux_random_point_in_unit_sphere 
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In the square shader, we reused a variable of type miVertex to provide the argument to the 

geometry API function mi_api_vector_xyz_add. Since we’ll always need to convert the x, y, and Prog 474, 4.2.8.3. Polygonal 
z components of the vector into a variable of type miVector, we'll define a function to simplify ici 

that conversion. 


void miaux_add vertex(int index, miScalar x, miScalar y, miScalar 2z) 


di: 
2 { 

3 miVector v; 

4 V.X = Xj} V.Y = Yj V.Z = Z; 
5 mi_api_vector_ xyz_add(&v) ; 
6 mi_api_vertex_add(index) ; 
7 


} 


Figure 19.11: Function miaux_add_vertex 


In miaux_add_vertex, the miVector type is used not to define a direction, but the coordinates 
of a point. If we keep track of the position of that miVector—its index in the list—we can also 
define it as a vertex in line 6. 


Now that we have simplified the process of defining an miVector to be used as a vertex in a 
polygon, we can define three vertices and the triangle as well. 


void miaux_add_random_triangle(int index, float edge_length_max, 
miVector *bbox min, miVector *bbox_max) 


int vertex index; 

float offset max = edge length_max / 2.0; 
float offset_min = -offset_max; 

EicaG x, V; @? 


miaux random point in unit _sphere(&x, &y, &Z)j; 

xX = Miaux fit(x, -.5, .5, bbox_min->x, bbox_max->x) ; 
y miaux fit(y, -.5, .5, bbox_min->y, bbox_max->y) ; 
Z = Miaux fit(z,, -.5, .5, Dbox_min->z, bbox max->2) ; 


miaux add vertex(index, x, y, 2); 

miaux_add vertex(index + 1, 
x + miaux_random_range(offset_min, offset_max), 
y + miaux_ random range(offset_min, offset_max), 
z + miaux_random_range(offset_min, offset_max)) ; 

miaux_add vertex(index + 2, 
x + mMiaux_random_range(offset_min, offset_max), 
y + miaux_random_range(offset_min, offset_max), 
z + miaux_random_range(offset_min, offset_max) ) ; 


mi_api_ poly begin _tag(1, 0); 

for (vertex index = 0; vertex_index < 3; vertex_index++) 
mi api poly index_add(index + vertex_index) ; 

mi api poly _end() ; 


Figure 19.12: Function miaux_add_random_triangle 


By passing the index of the first vector to be added and incrementing that index in the loop 
in lines 25-26, we can call miaux_add_random_triangle repeatedly in a geometry shader— 
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we’ve removed the limitations imposed by the use of constant numeric values in our square 


shader. 


The arguments bbox_min and bbox_max in line 2 define a bounding box which describes the three- 
dimensional extent of the set of triangles the function will construct. A rectangular box can be 
defined by two points: the point in which the x, y, and z values are all the minimum values for 
the box, and the point for which they all are at a maximum. For example, Figure 19.13 shows the 
bounding box that encloses a sphere. 


Sl 


Figure 19.13: A bounding box enclosing a sphere 


By passing the definition of a bounding box to the function, we can rescale the points in a 
unit sphere we calculate in line 9 and place them at an arbitrary point in space within that box. 
(Bounding boxes will become especially important as we look at placeholder objects later in the 
chapter). 


The creation of the triangular polygon in lines 24-27 uses the same API functions as the square 
shader. The indices of the vertices are an offset from the index passed as an argument to the 
function. The index argument will allow us to call miaux_add_random_triangle repeatedly ina 
geometry shader. 


The declaration of the parameters for a geometry shader is the same as for material shaders. As 
with material shaders, we can also provide default values for the parameters, so that some kind 
of object will be created even if the parameters do not have values in the scene file. 


declare shader 
geometry "triangles" ( 
string "name", 
integer "count" default 100, 


vector "bbox_min" default -.5 -.5 -.5, 

vector "bbox max" default .5 .5 .5, 

scalar "edge length max" default 1, 

integer "random _seed" default 1955 ) 
end declare 


Figure 19.14: Shader declaration of triangles (p.536) 
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The final parameter, random_seed, solves a problem when you want to use a sequence of random 
numbers in a shader, but want the same sequence each time you use the shader. Random numbers 
in a computer program are not truly random, but generated by a process that takes an initial 
value, or the random seed, to define how that apparently random sequence is generated. (This 
contradictory ability to control randomness is why random numbers generated in software are 
often called pseudo-random numbers.) 


The name parameter to triangles is our second use of a string parameter in a shader. In the 
contour Output shader in Section 10.6, c_output, we defined an output filename as a string. 
Here we use miaux_tag_to_string once again to convert the tag in the scene database to acquire 
the name for the object created by the shader. 


The core of the triangles shader is a loop controlled by the count parameter containing a call 
to the function miaux_add_random_triangle. 


struct triangles { 
miTag name; 
miInteger count; 
miVector bbox min; 
miVector bbox max; 
miScalar edge length_max; 
miInteger random_seed; 


}3 


miBoolean triangles ( 
miTag *result, miState *state, struct triangles *params ) 


eo 
NFOWUMIHDUABWNH 


int vertex_index; 
miObject *obj; 
miInteger count = *mi_eval_ integer (&params->count) ; 
miVector *bbox_min = mi_eval_vector(&params->bbox_min) ; 
miVector *bbox_max = mi_eval_ vector (&params->bbox_max) ; 
miScalar edge length_max = *mi_eval_ scalar (&params->edge_ length_max) ; 
char* name = 
miaux_tag to _string(*mi_eval_ tag(&params->name), "::triangles") ; 


L3 
14 
12 
16 
LL? 


NR R 
OW © 


mi_srandom(*mi_eval_integer (&params->random_seed) ) ; 


DON ND 
WN FR 


obj = mi_api_object _begin(mi_mem_strdup (name) ) ; 
obj->visible = miTRUE; 
obj->shadow = 3; 


WN 
UT is 


NN N 
co ~J OF 


mi_api_object_ group begin(0.0) ; 
for (vertex_index = 0; vertex_index < count * 3; vertex_index += 3) 
miaux_add_random_triangle ( 
vertex_index, edge_length_max, bbox_min, bbox_max) ; 
mi_api_object_group_end()j; 


WW ND 
ro wo 


return mi_geoshader_add_result (result, mi_api_object_end())j; 


WWW W 
OB WN 


Figure 19.15: Shader source of triangles (p.536) 


The call to mi_srandom in line 22 uses the shader’s random_seed parameter to define the 
sequence of random numbers. The same random_seed parameter will create the same set 
of “random” triangles. By extracting the primary action of the shader into the function 
miaux_add_random_triangle, the shader consists of the straightforward acquisition of parameter 
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values in lines lines 15-20 and the standard creation of an object in lines 24-34. Once we are 
certain that this structure is in place, we can focus the more difficult task of debugging the function 
that creates the triangle data in lines 30-31. 


19.3. Placeholder objects 


In the shaders in the previous sections, the construction of geometry occurs before actual 

rendering begins. You can also delay the creation of geometric data until it is required during 

Rend 369, 13.7. Demand- rendering—until a ray intersects the representative for that object, its placeholder object. For 
mene EGeHenies large scenes, this can result in a significant improvement in the speed of rendering. 


Geometry 
In this section, we'll look at four placeholder object techniques: 
1. Creating an object from a file specified in the scene; 
2. Creating an object from a file within a shader; and 
3. Creating an object instance from file within a shader. 
In the next chapter, we’ll look at the most flexible placeholder mechanism of all, creating geometric 
data through a callback function. 
19.3.1 Creating an object from a file specified in the scene 
To create an object file we can use ina placeholder object, we'll start with a scene file fragment like 
the square we defined in Section 19.1. We’ll define a triangular polygon, the simplest polygon 
we can make, and save this in a file called triangle_object.mi. 
incremental 
object "triangle-object" 
visible on 
shadow 3 
0 
001 
000 
100 
010 
V n 
V n 
V n 
p 1 
end group 
end object 
Figure 19.16: Object file triangle_object.mi with the incremental command 
Rend 369, 13.7. Demand- To use this file in a placeholder object, we specify the filename with the file statement in the 


loaded Placeholder 


rs object definition. 
eometry 
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material "diffuse" 
"lambert" ( 
Mighta” [“Lighh-inet")] 4 
end material 


object "triangle-object" 
visible 
shadow 3 
box -.5.3:5 -,.1 .5_.5)<l1 
File "triangle object.mi" 


end object 


instance "triangle-instance" "triangle-object" 
material "diffuse" 
transform 


Figure 19.17: Object data read from file using the file statement in the object block 


How does mental ray know when to read the object file into the placeholder object? Notice 
the command incremental before object in the object file. In mental ray, incremental changes 
can be made to the scene database constructed during rendering. During the construction of 
the scene, the initial object that is added to the database is only a bounding box that encloses 
the object. We used the minimum and maximum points of the bounding box in our triangles 
shader as two parameters to define the bounding box within which we created triangles. For 
placeholder objects, a box statement in the object’s definition defines the bounding box, listing 
the xyz components of the minimum and maximum point as its arguments. In Figure 19.17, the 
object named triangle-object includes a box statement. Figure 19.18 shows the bounding box 
used for the triangle in Figure 19.17. 


Figure 19.18: A bounding box that encloses a polygon with a greater thickness than necessary 


The depth of the bounding box in Figure 19.17 is larger than necessary—this is not considered 
an error by mental ray, but bounding boxes should be as small as possible and still enclose the 
object so that the object file is not read unnecessarily. 


Rend 393, 16. Incremental 
Changes and Animations 


284 19 Creating geometric objects 


19.3.2 Creating an object from a file within a shader 


An object defined in a scene file fragment with the incremental command can also be read by 
Prog 472, 4.2.8. Geometric | mental ray ina shader. The function mi_api_object_file takes the filename as an argument and 
Objects is the API equivalent of the file statement in the object block. 


We’ll define an auxiliary function called miaux_object_from_file that takes a filename for the 
incremental object as well as the bounding box points as arguments. 


miTag miaux_object_from_file( 
const char* name, const char* filename, 
miVector bbox_ min, miVector bbox_max) 


miObject *obj = mi_api_ object begin(mi_mem_strdup (name) ) ; 
obj->visible = miTRUE; 

obj->shadow = 3; 

obj->bbox min = bbox_min; 

obj->bbox_max = bbox_max; 

mi_api_ object file(mi_mem_strdup (filename) ) ; 

return mi_api object end() ; 


Figure 19.19: Function miaux_object_from_file 


We'll use miaux_object_from_file in a shader, object_file, that specifies the object filename 
as a parameter. 


declare shader 
geometry "object_file" ( 
string "name", 


string "filename", 

vector "bbox min" default -1 -1 -1, 

vector "bbox_ max" default 111 ) 
end declare 


Figure 19.20: Shader declaration of object_file (p.537) 


Since the auxiliary function miaux_object_from_file returns the object tag, we can call it directly 
in mi_geoshader_add_result. 
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struct object file { 
miTag name; 
miTag filename; 
miVector bbox_min; 
miVector bbox_max; 


ti 


miBoolean object file ( 
miTag *result, miState *state, struct object_file *params ) 


OANA UH FPWN HE 


char *name, *filename; 


if (! (name = miaux_tag to string(*mi_eval _tag(&params->name), NULL)) | | 
!(filename = miaux_tag_ to string(*mi_eval_tag(&params->filename), NULL) ) ) 
return miFALSE; 


return mi_geoshader_add_result ( 
result, 
miaux object from _file(name, filename, ; 
*mi_eval_ vector (&params->bbox_min), 
*mi_ eval vector (&params->bbox_max) ) ) ; 


Figure 19.21: Shader source of object_file (p.537) 


Shader object_file is an example of a condensed C programming style in which we reduce 
temporary variables as much as possible. Since the value of an entire assignment statement is the 
assigned value itself, we can assign values to variables name and filename as well as check that 
they are not NULL in the if clause in lines 13-14. 


material "diffuse" 
"lambert" ( 
"lights" ["light-inst"] ) 
end material 


instance "triangle-instance" 
geometry 
"opject tile” { 
"name" "::triangle-object", 


"filename" "triangle object.mi", 
"bbox_ min" . . -.01, 
"bbox_ max" . ‘ 201, ) 

material "diffuse" 


transform 
100 
010 
001 
0 -.2 
end instance 


Figure 19.22: Object data read from file in the shader object_file 


In shader object_file, both the name and the filename are specified in the shader parameters. 
For such a small scene, we could have used a default name built into the shader function itself. 
However, when we make multiple instances in the next section, we'll need to make sure that each 
name is unique. 
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19.3.3. Creating an object instance from file within a shader 


In shader object_file, we created an object from a file, and used this as the object data for the 
instance block in the scene file. We can also create multiple instances within a shader, creating 
Prog 469, 4.2.7. Instancesand an instance group. For this shader we’ll use a slightly more complex object. Any object file can 
Instance Groups b d in thi -th l . is th f the 3 
e used in this way; the only requirement is the use of the incremental statement. 


incremental 

object "wedge-object" 
visible on 
shadow 3 


group 


v2v3v4v 5 


1 

2 

5 

4 3 

5 4 
1 3 5 
end group 


end object 


Figure 19.23: Object file wedge_object.mi 


For shader instanced_object_file, we will create multiple instances of the object defined 
in filename, each translated by the position in a list of vectors defined by parameter 
positions. 


declare shader 
geometry "instanced object file" ( 
string "name", 
string "filename", 


material "material", 
vector "bbox min" default -<1 <1 =1, 
vector "bbox_max" default 11 1, 
array vector "positions" ) 

end declare 


Figure 19.24: Shader declaration of instanced_object_file (p.538) 


In shader instanced_object_file, we again use the auxiliary functionmiaux_object_from_file 
to get an object tag. But rather than add this object to the scene, we use the tag in a loop to create 
a set of object instances. 
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struct instanced object file { 
miTag name; 
miTag filename; 
miTag material; 
miVector bbox_min; 
miVector bbox_max; 
int i positions; 
int n_positions; 
miVector positions [1] ; 


ANIA UF WN EH 


Ne) 


i. 


miBoolean instanced object file ( 
miTag *result, miState *state, struct instanced object file *params ) 


PRPRPRPRP PB 
Uh WNHO 


int i; 
Static int instance index; /* Geometry shaders are single-threaded. */ 
char *filename, *name, instance_name [1024]; 
miInstance *instance; 
miTag object _tag, instance tag; 
int position count = *mi_eval_integer(&params->n_positions) ; 
miVector *positions = mi_eval_vector(params->positions) + 
*mi_eval_ integer (&params->i positions) ; 


a 
© ~1 0 


MONMNNH 
wor Oo wo 


NO 
WwW 


if (!(name = miaux_ tag to string(*mi_eval _tag(&params->name), NULL)) | | 
!(filename = miaux_tag_to_string(*mi_eval_tag(&params->filename), NULL) ) ) 
return miFALSE; 


NON 
O1 & 


object _tag = miaux_object from file(name, filename, 
*mi_eval_ vector (&params->bbox min), 
*mi_eval_ vector (&params->bbox_max) ) ; 


26 
or 
28 
ee | 


for (i = 0; i < position count; i++, positions++) { 
miMatrix matrix; 
miTag material tag; 
sprintf (instance name, "%s-%d", name, instance_index++) ; 
if (! (instance = mi_api_instance begin(mi_mem_strdup (instance_name) ) ) ) 
return miFALSE; 


WWW WW W 
Mm PF WNH O 


mi_matrix ident (matrix) ; 

matrix[12] = positions->x; 

matrix[13] = positions->y; 

matrix[14] = positions->z; 

mi matrix copy (instance-stf.local_ to global, matrix) ; 

mi_matrix_ invert (instance->tf£.global_to local, 
instance->tf.local_ to global); 


PoP PB PB WW Ww WwW 
BWNHROWw AND 


Be B® 
oO Ul 


material tag = *mi_eval_tag(&params->material) ; 
if (material tag) 
instance->material = mi_phen _clone(state, material _ tag) ; 


instance tag = mi_api_instance_end(0, object_tag, 0); 

if (instance tag == miNULLTAG | | 
mi_geoshader_add_result (result, instance_tag) == miFALSE) 
return miFALSE; 


Nuon uo PP 
PWN OW OW ~I 


Ul 
O1 


} 


return miTRUE; 


U1 U1 
1 Oo 


Figure 19.25: Shader source of instanced_object_file (p.538) 


Like shader object_file, we test for argument validity in lines 24-26. In lines lines 20-22 the 
array of vectors is evaluated based on the typical set of three fields in the shader’s parameter struct 
in lines 7-9. This array of vectors is the basis for the loop in lines 32-55, with the components 
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of each vector defining the translation portion of a transformation matrix in lines 40-42. We'd 
like the vectors in the scene file to be in world space, so we effectively invert them for use in the 
matrices of the instance in lines 43-45. If a material has been specified in the shader parameters, 
we assign a copy of it to the instance in line 49. If there is an error either in defining the instance 
or in adding it to the scene (in lines 51-53), we return miFALSE immediately in line 54. 


material "amb_occlude" 
"ambient occlusion cutoff" ( 
"Samples" 200, 
"“sutort distance" 9 ) 
end material 


instance "triangle-instance" 
geometry 
“instanced object file" ({ 
"name" "::wedge-object", 
"filename" "wedge object.mi", 


"hte min” =,5+,8'=.OL, 
"bbox max" .5 .5 .01, 
"material" "amb occlude", 
"positions" 
[ -0O. 0 2. 
QO. oO =L. 


Os -25 -1. 
cite @=Ls 
-75 -1. 
9 
end instance 


Figure 19.26: Multiple instances created from a file in shader instanced_object_file 


For the positions parameter, the list of vectors is separated by commas and surrounded by square 
brackets. The syntax for the individual vectors in an array is the same as a vector parameter, three 
numbers separated by spaces. 


Chapter 20 


Modeling hair 


In the previous chapter, we created geometric objects not by parsing a scene file, but through 
calls to the functions defined in the geometry shader API and declared in geoshader.h. At first 
blush, it hardly seems worth the trouble to make a handful of triangles with all the complexity of 
a geometry shader—a program written in a scripting language like Python could generate a scene 
file that would accomplish the same thing. 


Geometry shaders become more obviously a useful solution when our problem involves the 
complexity of modeling natural phenomena. For example, the look of human hair is the result 
of both lighting and geometric complexity, and has become a compelling problem for both 
researchers and production programmers alike. In mental ray, the geometric hair primitive 
provides a means for large scale geometric datasets that have been optimized for rendering and 
yet still allow for the fine level of detail required for realistic hair modeling. 


20.1. Placeholder objects and callback functions 


A callback is a function that is defined by another function to be called at a later time. In geometry 
shaders, a callback function creates the actual geometric data of the shader. The shader itself only 
defines a bounding box for that data and registers the callback. When a ray enters the bounding 
box defined by the shader, the callback function is run to create the data required for rendering. 
In this way, the creation of complex geometry can be deferred until it is actually needed at 
rendering time. This is a deferral in the same spirit as the shaders of the last chapter, in which 
the actual construction of geometry was delayed until required during rendering. However, the 
callback function can also perform arbitrary additions to the scene database using the geometry 
API functions. 


Creating geometric forms through callback functions can address levels of geometric complexity 
that could not be modeled “by hand” through a typical graphical interface. The mental ray 
geometry API includes the creation of a geometric primitive miOBJECT_HAIR as one of the 
enumeration mi0bject_type in geoshader.h. The hair primitive is optimized for the fine 
geometric structure required to simulate the appearance of hair-like objects. However, we need 
to be careful about the conceptual restrictions of the metaphor. As we’ll see later in the chapter, 
the hair primitive can also be used for other effects—plants, water, fire—that are unrelated to 
actual hair. 


Prog 473, 4.2.8. Geometric 
Objects 


Prog 535, 4.3.9. Objects 
Prog 526, 4.3.9. Objects 


Prog 483, 4.2.8.7. Hair 
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20.2 Structure of the shader and its callback 


The contract of a shader using a callback function overlaps with the actions of the callback 
function itself. 


The shader: 
1. Evaluates parameters and saves them in a structure 
2. Creates the placeholder object: 
2.1. Defines the object bounding box 
2.2. Specifies values for object options (e.g., shadow casting) 
3. Registers the callback function, passing the parameter structure 


The callback function: 
1. Sets incremental mode 
2. Creates the object in the same manner as the shader: 
2.1. Defines the object bounding box 
2.2. Specifies values for object options (e.g., shadow casting) 
3. Defines the actual object geometry 


In callback functions that use the hair primitive, fair data arrays are created in the third step. For 
efficiency, the “hair shaders” in this chapter, the shader functions simply evaluate their parameters 
and register the callback function. The diversity of techniques in using the hair primitive are 
therefore restricted to the callback functions alone. 


20.3. Basic principles of the hair geometric primitive 


Efficient representation of large numbers of ribbon-like curves is the primary purpose of the hair 
primitive. The definition of a hair only requires a set of hair vertices that form its shape and a 
hair radius that defines its thickness. 


| radius 
V1 v2 @ 


Figure 20.1: Single hair with two hair vertices 


The hair radius and vertices are represented in a hair scalar array. For the simple hair of 
Figure 20.1, the hair scalar array only consists of the radius and the vector components. Another 
array, the hair index array, defines the extent of each hair’s data in the scalar array. A final entry 
in the index array marks the end of the scalar array with a value that is one greater than the index 
of the final scalar array element. In Figure 20.2, the index array would simply be {0,7}. 


index #1 radius 
end marker "ee 
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| 
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Figure 20.2: One hair with one segment (two vertices) and a radius for the entire hair 
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For a linear hair curve, each vertex is a point along the hair path. Additional vertices extend the 
length of the hair and can give it an arbitrary shape. The end of each segment 1s a semi-circle 
centered on the vertex so that additional segments create a continuous surface. 


Figure 20.3: Single hair with three hair vertices 


Quadric and Beziér hair curves use the vertices in the scalar array as control points. The number 
of points that approximate the curve are part of the hair definition. 


v1 e v3 


Figure 20.4: Single hair with four hair vertices and Beziér curve (degree = 3, approximation = 10) 


Additional vertices are simply appended to the scalar array, with the index array defining the 
number of vertices per hair. 


index #1 
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end marker . 
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Figure 20.5: One hair with two segments (three vertices) and a radius for the entire hair 


Internally, mental ray represents the geometric shape of the hair as a flat surface that is always 
oriented toward the camera. At the typical size of hairs during rendering, this optimization isn’t 
noticeable. However, the shading techniques we have used in other shaders based on the fields 
of the state shader argument will not all be possible. 
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Prog 209, 3.4.4. Intersection The miState structure includes barycentric coordinates as field bary, describing the position of 
the ray’s intersection point in the current geometric primitive. (We displayed the barycentric 
coordinates as colors in Section 10.9.1.) For hairs, however, the barycentric coordinates define 
the relative position of the intersection point on the hair in a different manner than the other 
geometric primitives. The first element in the state->bary array describes the position across 
the width of the hair, the second element describes the position along the hair’s length, both 
represented as values from 0.0 to 1.0. 

| radius 


state->bary [0] 


state->bary [1] 


Figure 20.6: Barycentric coordinates describing the size of the hair 


For each additional vertex, the length represented by state->bary[1] at each point in the hair 
is the fraction of the total length of all segments. 


Figure 20.7: Length in state->bary [1] defined by the length of line segments connecting vertices 


For quadric and Beziér curves, the hair vertices are used as control points for the curve. The 
approximation points create a series of segments used in the length calculation. 


Figure 20.8: Beziér curve length defined by segments created from approximation points 


20.4 Ageometry shader for a single hair 


Our first hair shader will only use two vertices to define a hair but it will serve as a model for the 
more complex hair shaders we’ll define later. In shader hair_geo_2v, the hair radius and its two 
vertices are specified as parameters. 
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declare shader 
geometry "hair geo 2v" ( 
string "name", 


scalar "radius" default .1, 

vector "start" default -0.5 0 0, 

vector "end" default 0.5 0 0 ) 
end declare 


Figure 20.9: Shader declaration of hair_geo_2v (p.540) 


As we saw in Section 20.2, both the shader and the callback function it registers duplicate many 
steps in the initial creation of the object. One of the more complex actions in both functions 
is the creation of the bounding box definition for the object. We'll define a bounding box 
creation function for each hair shader, and use this function for both the shader and the callback 
function. First, however, we’ll define a few utilities that will simplify the definition of a bounding 
box. 


The bounding box is stored in two miVector fields of the mi0bject struct, bbox_min and 
bbox_max. Our first utility function initializes these vectors. 


void miaux_init_ bbox(miObject *obj) 

{ 
obj->bbox_min. miHUGE SCALAR; 
obj->bbox_min. miHUGE SCALAR; 
obj->bbox_min.z = miHUGE_ SCALAR; 
obj ->bbox_max. -miHUGE SCALAR; 
obj->bbox_ max. -miHUGE SCALAR; 
obj->bbox_max. -miHUGE SCALAR; 


Figure 20.10: Function miaux_init_bbox 


Now for any point (represented by an miVector), we can increase the size of the bounding box 
in the object by comparing a new value to it. Since we express hairs as vertices and a radius, we'll 
specify an additional length (the radius) to increase the extent of the new value (a hair vertex). 
We may also find this extra length useful to resolve issues of numerical precision. 


void miaux_adjust_bbox(miObject *obj, miVector *v, miScalar extra) 


{ 


miVector v_extra, vmin, vmax; 
Miaux set vector (&v_extra, extra, extra, extra); 


mi vector sub(&vmin, v, &v_extra) ; 


mi vector add(&vmax, v, &v_extra) ; 
mi vector min(&obj->bbox_min, &obj->bbox_min, &vmin) ; 
mi vector max(&obj->bbox_max, &obj->bbox_max, &vmax) ; 


Figure 20.11: Function miaux_adjust_bbox 


We’ll want to see the calculated bounding box (in a manner similar to what mental ray does 
during scene construction), so we’ll define another function for a message to be displayed during 
scene construction when geometry shaders are executed. 


Prog 526, 4.3.9. Objects 
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void miaux_ describe bbox(miObject *obj) 


{ 


1 
2 
3 mi progress ("Object bbox: %f,%f,%f % 
5 
6 


obj->bbox_min.x, obj->bbox_min.y, obj->bbox_min.z, 
obj->bbox_max.x, obj->bbox_max.y, obj->bbox_max.z) ; 


} 


Figure 20.12: Function miaux_describe_bbox 


We now have the utilities we need for the creation of a simple bounding box function. But to 
be able to use a single function for the initial object construction of a hair, it will be useful to 
pass a bounding box function name as an argument. We need to therefore decide on a consistent 
function signature for the bounding box function. All the shaders in this chapter define bounding 
box functions that take two arguments: the object being constructed, and the parameters of the 
geometry shader. 


typedef void (*miaux_bbox function) (miObject*, void*) ; 


Figure 20.13: Bounding box creation function type miaux_bbox_function 


For our first hair shader, then, the bounding box creation function uses the two hair vertices 
passed as parameters to define the bounding box, defined by the parameter struct for the shader 
we re writing, hair_geo_2v. 


1 typedef struct { 

2 miTag name; 

3 miScalar radius; 
5 
6 


miVector start; 
miVector end; 
} hair _geo 2v t; 


Figure 20.14: Source code of struct hair_geo_2v_t (p.540) 


Notice that we’re using C’s typedef facility to define a new type that is a struct of parameters. 
In our previous shaders, we have used the struct syntax for the shader, since we only needed to 
use it once. Here, since we are using the parameter structure in several places, we define a new 
type with typedef. (Using typedef here, in some ways, is a matter of style—you could choose 
to use typedef for the parameter structs in all of your shaders. 


Now we have all the pieces we need to define a bounding box function for shader 
hair_geo_2v. 


void hair geo 2v_bbox(miObject *obj, void* params) 
{ 
hair geo 2v_t *p = (hair _geo_2v_t*)params; 
miScalar bbox_increase = p->radius + .001; 


miaux_adjust_bbox(obj, &p->start, bbox_increase) ; 
miaux_adjust_bbox(obj, &p->end, bbox_ increase) ; 


Ai 

a 

2 

4 

5 miaux_init_bbox(obj) ; 

6 

7 

8 miaux_ describe bbox(obj) ; 
9 


} 


Figure 20.15: Shader source of hair_geo_2v (p.540) 


20.4 Ageometry shader for a single hair 295 


To create a general function to be used in several different hair shaders, we need to define the 
parameter argument as a pointer to void, and then cast it to the appropriate parameter type in 
the shader, as we do in line 3. We then use our utility functions to adjust the bounding box in the 
miQObject containing the hair definition that we passed as the first argument to hair_bbox. 


Now that we’ve specified a consistent function signature for a function that defines an object’s 
bounding box, we can define a general purpose function for our miaux library that defines an 
object in both the hair shader and in its callback and passes the bounding box function name as 
an argument. 


void miaux_define hair object ( 
miTag name_tag, miaux_bbox function bbox_ function, void *params, 
miTag *geoshader_ result, miApi_ object callback callback) 


miTag tag; 

miObject *obj; 

char *name = miaux_tag to _string(name_tag, "::hair") ; 

obj = mi_api_object_begin(mi_mem_strdup (name) ) ; 

obj->visible = miTRUE; 

obj->shadow = obj->reflection = obj->refraction = 3; 

bbox_function(obj, params) ; 

if (geoshader_result != NULL && callback != NULL) { 
mi_api_object_callback (callback, params) ; 
tag = mil_api_object_end(); 
mi_geoshader_add_ result (geoshader result, tag) ; 
obj = (miObject *)mi_scene_ edit (tag) ; 
obj->geo.placeholder list.type = miOBJECT HAIR; 
mi scene edit end(tag) ; 


Figure 20.16: Function miaux_define_hair_object 


The bounding box function, passed as the second argument in line 2, is called in line 11. 
Line 12 checks the arguments geoshader_result and callback because lines 13-18 are 
only required in the shader and not in the callback. The call back will pass NULL to these 
arguments for this conditional. Line 13 registers the callback function that was passed to 
miaux_define_hair_object as its final argument. Notice that to define the object placeholder 
as type miOBJECT_HAIR, we have to update the scene database with the object we have defined in 
line 15, and then edit the scene database in lines 16-18 with API functions mi_scene_edit and 
mi_scene_edit_end. 


Now with all the initial object definition consolidated in a utility function, the shader function 
hair_geo_2v only needs to evaluate its parameters, passing the resulting struct to function 
miaux_define_hair_object to initialize the creation of the hair object. 
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miBoolean hair geo 2v ( 


{ 


miTag *result, miState *state, hair _ geo 2v_t *params ) 


hair geo 2v_ t *p = (hair geo 2v_t*)mi_mem_allocate(sizeof (hair_geo 2v_t)); 
p->name = *mi_eval_tag(&params->name) ; 

p->radius = *mi_eval_scalar(&params->radius) ; 

p->start *mi_eval_ vector (&params->start) ; 

p->end = *mi_eval_vector (&params->end) ; 


miaux define hair object ( 
p->name, hair_geo_2v_bbox, p, result, hair_geo_2v_callback) ; 


return miTRUE; 


Figure 20.17: Source code of shader hair_geo_2v (p.540) 


The shader hair_geo_2v has relegated the actual work to function hair_geo_2v_callback which 
is responsible for the creation of the hair’s scalar and index arrays. 


miBoolean hair_geo 2v_callback(miTag tag, void *params) 
{ 

miHair list *hair list; 

miScalar *hair scalars; 

miGeoIndex *hair_indices; 

hair_geo 2v_t *p = (hair_geo 2v_t*)params; 

int hair scalar count = 7; 


mi api incremental (miTRUE) ; 
miaux_define hair object (p->name, hair _geo 2v_bbox, p, NULL, NULL); 


hair list = mi_api_ hair begin() ; 
hair _list->degree = 1; 
mMi_api_ hair info(0, *r’, 1); 


hair scalars = mi_api_hair_ scalars begin(hair_ scalar count) ; 
*hair scalars++ p->radius; 

*hair_scalars++ = p->start.x; 

*hair_ scalars++ p->start.y; 

*hair scalars++ p->start.Z; 

*hair_scalars++ p->end.x; 

*hair scalars++ p->end.y; 

*hair scalars++ = p->end.z; 
mi_api_hair_ scalars _end(hair_ scalar count) ; 


hair_indices = mi_api_hair_hairs begin(2) ; 
hair _indices [0] 0; 

hair_indices[1] = 7; 
mi_api_hair_hairs end() ; 


mi_api_hair_end() ; 
mi_api_object_end()j; 


return miTRUE; 


Figure 20.18: Shader source of hair_geo_2v (p.540) 


The incremental statement in the scene file we saw earlier in the chapter is implemented in a 


Prog 473, 4.2.8. Geometric callback function with the geometry API call mi_api_incremental in line 9. In line 10, we call 
Objects 
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our utility function to create the initial object definition, passing NULL as the last two arguments 
to signal that the function is being executed in the callback, and not in the shader. The variable 
hair_list of type miHair_list, declared in line 3, contains information about the geometric 
type of the hair. In line 13, we specify that the hair is linear (a degree of 1) so that the hair curve 
will pass through the vertices. 


The function mi_api_hair_info defines all other information about the hair besides the positions 
of the vertices. 


Argument Values 


where entire hair (at beginning of scalar array) 
each vertex 


what radius 


0 

2 

r 

t texture 
n normal 

m motion 

u_—cuser data 

num Number of scalars used 


Figure 20.19: Argument values for mi_api_hair_info 


In line 14, the hair is defined to have a radius value for the entire hair and will occupy one element 
of the scalar array. Because it is defined for the entire hair, the radius value is placed before the 
vertex data in the scalar array. 


Line 16 defines the hair scalar array, using hair_scalar_count to define its size. In lines 17- 
23, we define the elements of the scalar array explicitly (though later shaders in this chapter will 
take a procedural approach for the creation of these values). Line 24 terminates the scalar array 
definition. Lines 26-29 define the hair index array which references the scalar array. With a 
single hair, the index array only has two elements—the index of the beginning of the scalar array 
(line 27) and the end marker (line 28). Lines 29-32 finish the definition of the index array, the 
hair arrays and the object itself. 


material "gray" 
"one color® <4 
"Color™ 
end material 


Lo instance "hair-instance" 


geometry 


"hair geo 2v" ( 
treaciup  ~. 71 
| 
Yene"- 5 .4 

material "gray" 
end instance 


Figure 20.20: One hair of two vertices rendered with constant color 
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Prog 483, 4.2.8.7. Hair 
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20.5 Visualizing the hair’s barycentric coordinates 


To better understand how the hair’s barycentric coordinates are defined for hairs, we'll define a 
shader to render them as colors. 


declare shader 


color "hair color bary" () 
end declare 


Figure 20.21: Shader declaration of hair_color_bary (p.541) 


Shader hair_color_bary is similar in spirit to show_uv from Section 9.1. We interpret non- 
color data as color to visualize the way the barycentric coordinates vary across the surface of the 
hair. 


miBoolean hair color bary ( 
miColor *result, miState *state, void *params ) 


result->r state->bary [0] ; 
result->g state->bary [1] ; 
result->b O; 
return miTRUE; 


Figure 20.22: Shader source of hair_color_bary (p.541) 


Because the shader does not require any parameters, but the third argument is required, we define 
it as a pointer to void. This shader can be useful to understand how an application translates the 
hair you define using a graphical interface into the actual hair primitives in the mental ray scene 
database. 


material "bary" 
"hair color bary" () 
end material 


instance "hair-instance" 
geometry 
"hair geo 2v" ( 
"radius" 


ma 
"Starc”™ =< 5 
"end" .5 .4 
material "bary" 
end instance 


Figure 20.23: Two-vertex hair rendered with shader hair_color_bary 


20.6 Higher order curves in the hair primitive 


To create smooth curves with straight line segments can require large numbers of vertices. With 
the number of curves required to do a simulation of hair, reducing the number of hair vertices 


20.6 Higher order curves in the hair primitive 


becomes very important. Quadric and Beziér curves use the hair vertices as control points, but 


are specified as field values of the hair list structure that contains the hair arrays. 


For example, we defined a linear curve in shader hair_geo_2v by specifying a degree of 1. The 


four vertices in Figure 20.24 would produce three segments. 


V1 


Figure 20.24: Degree parameter of 1 with vertices connected by straight lines 
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We'll define a shader called hair_geo_4v in which we can pass curve control fields tomiHair_list 
as shader parameters, as well as four vectors that will define the vertices of the hair. 


declare shader 


geometry "hair geo 4v" ( 
"name" , 


string 
scalar 
vector 
vector 
vector 
vector 


"radius" default 


Ward W" 
Wy7D W 
Ny73 W 
NWx74 W 


/ 


default -. 
default 
default 1. 0 


Al 
default -1. 0 
0 
0 


integer "approximation" default 2, 
integer "degree" default 1 ) 


end declare 


Figure 20.25: Shader declaration of hair_geo_4v (p.542) 


By using a degree parameter value of 1, we produce a hair of three segments. 


Figure 20.26: Hair curve with a degree value of 1 rendered with shader hair_color_bary. 


material "bary" 
"hair color bary" () 


end material 


instance "hair-instance" 


geometry 


"hair geo 4v" ( 


material 
end instance 


"name" "::hair-1", 

"radius" 

Wy W -,. 6 

Wx72 W O -. 

Wy73 W O 

Nx74 W 7 6 

"degree" 
"bary W 
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If we specify a degree parameter value of 2, however, we can produce a quadric curve, and with 
degree 3, a Beziér spline. The curve is defined by an approximation that specifies the number of 
points along the ideal curve that is used to create the actual segments of the hair. 


V1 


Figure 20.27: Beziér curve (degree=3, approximation=20) defined by four vertices 


Shader hair_geo_4v also includes an approximation parameter for use in the initial definition 
Prog 528, 4.3.9. Objects of the miHair_list structure. 


material "bary" 
"hair color bary" () 
end material 


instance "hair-instance" 
geometry 
"hair geo 4v" ( 
"name" "::hair-1", 
"radius" .1 
a ye = 
Wa" © =.b 
yo" Q «fF OD, 
va" 6 «7% GD, 
"approximation" 30, 
"degree" 3 ) 
material "bary" 
end instance 


Figure 20.28: Hair curve with a degree value of 3 rendered with shader hair_color_bary 


Like shader hair_geo_2v, the bounding box function for hair_geo_4v adjusts the initial empty 
bounding box by calling miaux_adjust_bbox for each vertex parameter. 


void hair_geo 4v_bbox(miObject *obj, void* params) 


hair _geo 4v_ t *p = (hair_geo 4v_t*)params; 
miScalar bbox_ increase = p->radius + .001; 
miaux_init_bbox(obj) ; 

miaux_adjust_bbox(obj, &p->vl1l, bbox_increase) ; 


miaux_adjust_bbox(obj, &p->v3, bbox increase 
miaux_adjust_bbox(obj, &p->v4, bbox_ increase) ; 
miaux_describe bbox(obj) ; 


/ 


) 
miaux_adjust_bbox(obj, &p->v2, bbox_increase) ; 

) 

) 


Figure 20.29: Shader source of hair_geo_4v (p.542) 


20.6 Higher order curves in the hair primitive 301 


With the shader function for hair_geo_4v, we can start to see the pattern for the rest of the hair 
shaders in this chapter. The shader function just evaluates the parameters and stores them in 
the parameter structure, calling miaux_define_hair_object to create the placeholder object and 
register the callback. 


1 typedef struct { 

2 miTag name; 

3 miScalar radius; 

4 miVector v1; 

5 miVector v2; 

6 miVector v3; 

7 miVector v4; 

8 miInteger approximation; 


9 miInteger degree; 
10 } hair _geo 4v t; 
H Sail 
12 miBoolean hair _geo 4v ( 
13 miTag *result, miState *state, hair geo 4v_t *params ) 
14 { 
5 hair geo 4v_t *p = (hair_geo 4v_ t*)mi_mem_allocate(sizeof (hair _ geo 4v_t)); 
16 p->radius = *mi_eval_ scalar (&params->radius) ; 
17 p->vl = *mi_eval_ vector (&params->vl1) ; 
18 p->v2 = *mi_eval_vector (&params->v2) ; 
19 p=->v3 = *mi_eval_vector (&params->v3) ; 
20 p->v4 = *mi_eval_ vector (&params->v4) ; 
21 p->approximation = *mi_eval_ integer (&params->approximation) ; 
22 p->degree = *mi_eval_ integer (&params->degree) ; 
ee 
24 miaux define hair object ( 
25 p->name, hair _geo 4v_bbox, p, result, hair _geo 4v_callback) ; 
26 
27 return miTRUE; 
28 } 


Figure 20.30: Source code of shader hair_geo_4v (p.542) 


Another pattern in the hair shaders in this chapter is the creation of a variety of auxiliary functions 
to simplify the creation of the hair arrays. For example, even in the creation of a single hair with 
four vertices, we can consolidate the assignment of vector components to the hair’s scalar array 
in a function to which we pass a pointer to the scalar array and the vertex to be inserted as an 
miVector. 


void miaux_append hair _vertex(miScalar **scalar_ array, miVector *v) 
(*scalar_array) 
(*scalar_ array) 
(*scalar_ array) 
*scalar_array + 


] = v->xX; 
] T= 2y7 
] V->Z; 
3 ° 


[0 
[1 
[2 


/ 


Figure 20.31: Function miaux_append_hair_vertex 


Given this auxiliary function, the shader callback hair_geo_4v_callback clarifies the use of the 
four vertex parameters as values for the scalar array. 
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miBoolean hair geo 4v_callback(miTag tag, void *params) 
miHair list *hair list; 
miScalar *hair scalars; 
miGeoIndex *hair indices; 
hair _geo 4v_t *p (hair _geo 4v_t *)params; 


int hair count = 1, hair_scalar_count = 4 * 3 + 1; 


mi api incremental (miTRUE) ; 

miaux define hair object(p->name, hair _geo_ 4v_bbox, p, NULL, NULL) ; 
hair list = mi_api_hair begin()j; 

hair _list->approx = p->approximation; 

hair list->degree = p->degree; 

mi_api_hair_info(0, ‘r’, 1); 


hair scalars = mi_api_hair_scalars_ begin(hair_scalar_count) ; 
*hair scalars++ = p->radius; 
miaux_append_ hair _vertex(&hair_ scalars, &p->v1) 
miaux_append hair _vertex(&hair_ scalars, &p->v2) ; 
miaux_append_ hair _vertex(&hair_ scalars, &p->v3) ; 
miaux_append_ hair vertex(&hair_ scalars, &p->v4) 
mi_api_ hair scalars end(hair_ scalar_count) ; 


/ 


Ul 


hair indices = mi_api_ hair hairs begin(hair_ count + 1); 
hair indices[0] = 0; 

hair _indices[1] = hair _scalar_count; 
mi_api_hair_ hairs end() ; 


mi_api_hair_end()j; 
mi_api_object_end() ; 


return miTRUE; 


Figure 20.32: Shader source of hair_geo_4v (p.542) 


Lines 12-13 set the curve control fields of the miHair_list initialized in line 11. Like shader 
hair_geo_2v, we use mi_api_hair_info to specify one radius per hair, inserted into the scalar 
array on line 17 for the twelve scalars of the vertex components in lines 18-21. 


Because the hair curve approximation controls the number of actual vertices along the curve, the 
appropriate value will depend upon the visual context for the curve. At smaller approximation 
values the quantization of the curve may become apparent. 


Figure 20.33: Beziér curve with approximation parameter of 4 


From Figure 20.34, however, we can see that the barycentric coordinates are still normalized across 
the surface of the curve, though discontinuities may occur at approximation points. This will 
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also be a consideration in the determination of the approximation field of miHair_list. 


material "bary" 
"hair color _bary" () 
end material 


instance "hair-instance" 
geometry 
"hair geo 4v" ( 
"name" ";:hair-1", 


ey ones: LaF 
wi as eG = 
Wx7D W -. ail 
ea" ae 
Sage Ge FD, 
"approximation" 4, 
"degree" 3 ) 
material "bary" 
end instance 


Figure 20.34: Hair curve of four vertices with a degree value of 3 


20.7. Additional data attached to the hair primitive 


Before we define large numbers of vertices using procedural techniques in the following sections, 
we'll extend shader hair_geo_4v to see how we can assign data to the individual vertices of the 
hair. Previously, we’ve been using a single radius for the entire hair. By defining per-vertex data, 
we can control the shape and color along the hair. 


Shader hair_geo_4v_texture includes parameters for a radius and color for the “root” (the first 
vertex) and “tip” (the last vertex) of the hair. We’ll determine the values of the inner two vertices 
by a weighted average of the root and tip values. 


declare shader 
geometry "hair geo 4v_texture" 
string "name", 
vector "v1" default 5 Q 
vector "v2" default -.5 0 
vector "v3" default 5 0 
vector "v4" default 1.5 0 


scalar "root_radius" default .1, 
eolor "root color” default 0 0 0 1, 
scalar "tip radius" default .01, 
color "tip color" default 111 0, 
integer "approximation" default 2, 
integer "degree" default 1 ) 

end declare 


Figure 20.35: Shader declaration of hair_geo_4v_texture (p.544) 


The alpha value for the root and tip colors will control the opacity of the hair. For quadric or 
Beziér curves, the values at the vertices are interpolated for intermediate points along the curve, 
creating a smooth value at higher approximation values for radius, color and opacity. 
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material "hair _color" 
"hair color texture" () 
shadow 
"hair color texture" () 
end material 


instance "hair-instance" 
geometry 
"hair_geo 4v_texture" ( 
"name" "::hair-1", 
Wy] W 
Wy7D W 
Wy73 W 
Wy7G W 
"root radius" 
"root color" 
"Cip radius" 
4p color’ 1 
"approximation" 20, 
"degree" 3 ) 
material "hair color" 
end instance 


Figure 20.36: Hair curve with radius and color control at each vertex 


When we specified one radius value for the entire hair, that radius value occurred first in the scalar 
array. For per-vertex data, each vertex begins with the xyz components of the vertex, followed 
by the additional vertex data. 
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Figure 20.37: One hair with four segments, with a radius and texture (color) for each segment 


First, following the pattern we’ve established for hair shaders, we need to define the bounding 
box for hair_geo_4v_texture. It’s the same as for hair_geo_4v_texture. 


void hair geo 4v_texture_bbox(miObject *obj, void* params) 


{ 


hair _ geo 4v_texture t *p = (hair_geo 4v_texture_t*)params; 
double max_radius = miaux_max(p->root_radius, p->tip radius) + .001; 


miaux init bbox(obj) ; 

miaux_ adjust _bbox(obj, &p->pl, max_radius) ; 
miaux_adjust_bbox(obj, &p->p2, max_radius) ; 
) 
) 


miaux adjust bbox(obj, &p->p3, max_radius) ; 


Ui 


miaux adjust bbox (obj, &p->p4, max radius 
miaux describe bbox(obj) ; 


Figure 20.38: Shader source of hair_geo_4v_texture (p.544) 
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As before, the hair_geo_4v_texture shader function stores the arguments into the parameter 
struct and calls miaux_define_hair_object. 


typedef struct { 
miTag name; 
miVector pl; 
miVector p2; 
miVector p3; 
miVector p4; 
miScalar root radius; 
miColor root color; 
miScalar tip radius; 
micoler tip color; 
miInteger approximation; 
miInteger degree; 

} hair_geo 4v_texture t; 


miBoolean hair _ geo 4v texture ( 
miTag *result, miState *state, hair _ geo 4v texture _t *params ) 


hair geo 4v_texture t *p = 

(hair geo 4v_texture t*) mi_mem_allocate (sizeof (hair geo 4v_texture t))j; 
p->pl = *mi_eval vector (&params->pl1) ; 
p->p2 *mi_eval vector (&params->p2) ; 
p->p3 = *mi_eval_ vector (&params->p3) 
p->p4 = *mi_eval_ vector (&params->p4) ; 
p->root_radius = *mi_eval_scalar(&params->root_radius) ; 
p->root_color = *mi_eval_color(&params->root_color) ; 
p->tip_radius = *mi_eval_scalar(&params->tip radius) ; 
p->tip_ color = *mi_eval_color(&params->tip_ color) ; 
p->approximation = *mi_eval_ integer (&params->approximation) ; 
p->degree = *mi_eval_ integer (&params->degree) ; 


1 


miaux define hair object ( 
p->name, hair _ geo 4v_ texture _bbox, p, result, 
hair geo 4v_texture_ callback) ; 


return miTRUE; 


Figure 20.39: Source code of shader hair_geo_4v_texture (p.544) 


In the callback, we'll use an auxiliary function, miaux_append_hair_data, to append additional 
data to the scalar array by passing a pointer to the scalar array value, updating the pointer after 
assigning the values for each vertex. 


void miaux_append_ hair data ( 
miScalar **scalar_array, miVector *v, miScalar position, 
miScalar root_radius, miColor *root, miScalar tip radius, miColor *tip ) 


O] = W=>sxk; 

1] V->y; 

2] V->Z; 

3] miaux_ fit (position, root _radius, tip radius) ; 

4] miaux fit (position, root->r, tip->r); 

5] miaux_ fit (position, root->g, tip->g); 

6] = miaux_fit (position, root->b, tip->b); 
7] = miaux fit (position, root->a, tip->a) 
8; 


(*scalar_array) 
(*scalar array) 
(*scalar_ array) 
(*scalar_array) 
(*scalar_ array) 
(*scalar_ array) 
(*scalar_ array) 
(*scalar_ array) 
*scalar_array + 


Ui 


[ 
[ 
[ 
[ 
[ 
[ 
[ 
[ 


Figure 20.40: Function miaux_append_hair_data 
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What determines the order of the additional vertex data? The callback calls the API function 
mi_api_hair_info to define the order of the data that follows the vertex components as well as 
the number of elements required for each item. 


miBoolean hair_geo 4v_texture_callback(miTag tag, void *ptr) 


{ 


- 

2 

3 miHair list *hair_ list; 

4 miScalar *hair scalars; 

5 miGeoIndex *hair indices; 

6 hair_geo 4v_texture t *p = (hair _geo 4v_texture t *)ptr; 
7 int i; 

8 


9 int hair_count = 1; 
10 int vertices per hair 
11 int scalars per vertex 
12 int hair_scalar_count = vertices per hair * scalars_per vertex; 
i 
14 miVector vertices [4] ; 
15 vertices [0] p->pl; 
16 vertices [1] p->p2; 
Le vertices [2] D->p3; 
18 vertices [3] p->p4; 
19 
20 mi_api_ incremental (miTRUE) ; 
21 
22 miaux_define hair object ( 
23 p->name, hair geo 4v_texture bbox, p, NULL, NULL) ; 
24 
25 hair list = mi_api_ hair begin(); 
26 hair _list->approx = p->approximation; 
27 hair list->degree = p->degree; 
28 i. opi hairy anto(i, *x*, 1); 
29 mi api ‘hair info(1, *t’, 4); 
30 
31 hair scalars = mi_api_ hair scalars begin(hair scalar count) ; 
32 for (1 = 0; i < vertices per hair; i++) 
33 miaux_append_ hair data ( 
34 &hair scalars, &vertices[i], 
35 Miaux £Fit(i, 0, vertices_per hair, 0, 1), 
36 p->root_radius, &p->root_color, p->tip radius, &p->stip_color) ; 
37 mi _api_ hair scalars end(hair_ scalar count) ; 
38 
39 hair indices = mi_api_hair hairs begin(hair_count + 1); 
40 hair indices[0] = 0; 
41 hair _indices[1] = hair_scalar_count; 
42 mi_api_hair hairs _end(); 
43 
44 mi_api_ hair _end()j; 
45 mi api object _end(); 
46 
47 return miTRUE; 
48 


Figure 20.41: Shader source of hair_geo_4v_texture (p.544) 


Lines 14-18 create an array of the four parameter vertices that define the hairs shape so that 
the four calls to miaux_append_hair_data can be consolidated into a single call in the loop of 
lines 32-36. The decision to use a loop rather than four explicit calls is clearly not required, but we 
are moving closer to the more procedural approach we'll take in the following hair shaders. 
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In line 28, mi_api_hair_info specifies that each vertex will include a radius with the value of 1 
for the first argument. In line 29, the ’t’ argument defines a color value that requires four array 
elements (one each for red, green, blue, and alpha). These calls to mi_api_-hair_info defines the 
order and structure of the data in the scalar array. 


The ’t’ argument in line 29 is short for “texture”, and the values stored in that call can be acquired 
from the state->tex_list array. Our material shader that uses these hair texture values is called 
hair_color_texture. 


declare shader 


color "hair _color_texture" () 
end declare 


Figure 20.42: Shader declaration of hair_color_texture (p.546) 


We’ve specified opacity in the alpha channel of our texture colors, so we’ll use techniques from 
the transparency shaders to blend the hair with the background. 


miBoolean hair_color_texture ( 
miColor *result, miState *state, void *params ) 


miColor hair color, opacity, background; 
miaux_copy color(&hair_color, (miColor*) &state->tex_list[0])j; 


if (state->type == miRAY SHADOW) { 
miScalar transparency = 1.0 - hair _color.a; 
result->r *= miaux_shadow_breakpoint (hair_color.r, transparency, 
result->g *= miaux_shadow breakpoint (hair _color.g, transparency, 
result->b *= miaux_shadow_breakpoint (hair_color.b, transparency, 
return miaux_all_ channels equal(result, 0.0) ? miFALSE : miTRUE; 

} 

miaux_copy_color(result, &hair_ color) ; 

miaux_set_channels(&opacity, result->a) ; 

mi opacity set(state, &opacity) ; 

if (result->a < 1.0) { 
mi_ trace transparent (&background, state) ; 
miaux_blend_channels(result, &background, &opacity) ; 


} 


return miTRUE; 


Figure 20.43: Shader source of hair_color_texture (p.546) 


In line 5, we copy the color from first texture space for the hair. We’ll be using this shader for 
both the shadow and color values for the hair. If we’re in a shadow shader (line 7), we calculate 
the transparency of the shadow using the breakpoint technique from the Shadows chapter. In 
lines 14-20, we take this value into account to determine the final, blended color, also setting the 
opacity in line 16 so we can use mental ray’s optimized scanline renderer, the rasterizer, when 
rendering large numbers of hairs. 
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Material "hair color" 
"hair color texture" () 
shadow 


"hair color texture" () 
end material 


instance "hair-instance" 
geometry 
"hair geo 4v_ texture" ( 
"ame" "sthair-1", 
Wy W 
Wy72 " 
Wy73 " 
Wy74 W 
"root radius" 
"soot color" 
"tip radius" 
"tip color" 
"approximation 
"degree" 3 ) 
material "hair color" 
end instance 


Figure 20.44: Hair curve with larger radius at tip 
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An instance can include multiple geometry shader calls in the same way that you can create lists 
of other shaders. In Figure 20.45, the two shader instances of hair_geo_2v create two hairs in 
the scene. 


material "bary" 
"hair color bary" () 
end material 


instance "hair-instance" 
geometry 
"hair geo 2v" ( 
"name" "::hair-1", 
"radius" 
“start” =, 
"ena" .5 
"hair _geo_2v" 
"name W W :: 
"radius" 
letarc”™ 
"end" .5 
material "bary" 
end instance 


Figure 20.45: Two hairs created with a list of geometry shaders 


However, the hair primitive is designed so that a single hair “object” can efficiently define any 
number of hairs. The hair scalar array is simply a list of miScalar values; the hair index array 
points to the beginning of the set of scalars for each hair. 


The placement of additional hair data, like the radius and texture color, is the same for each hair 
in the scalar array. For example, if the radius is defined once for each hair, it will occur at the 
beginning of each hair, as in Figure 20.46. 
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Figure 20.46: Two hairs (A and B) with one segment each and a single radius for each hair 


Per-vertex hair data is included after the vertex components for each hair in the same way as for 
a single hair. In Figure 20.47, a separate radius is defined for each vertex. 
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Figure 20.47: Two hairs (A and B) with two segments each and a radius for each segment 


Ava 


In our next shader, hair_geo_row, we control the number of hairs to be constructed and their 
thickness by a shader parameter. 
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declare shader 


geometry "hair geo row" 
string "name", 
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( 


integer "count" default 1, 


scalar 
vector 
vector 
scalar 
scalar 


default .01, 

"bbox min" default -.5 =-.5 <.5, 
"Dbhox mage ines fad fea Ging Se ra Bay 

"y offset. max" -detault..04, 

"Zz offset.max" default: 102, 


integer "approximation" default 100, 
integer "degree" default 3, 
integer "random seed" default 1955 ) 


end declare 


Figure 20.48: Shader declaration of hair_geo_row (p.547) 


The shader defines the four corners of a rectangle in which a Beziér hair is defined. The rectangle 
for each hair is randomly offset in y and z, and distributed evenly within a bounding box in x. 
Creating a hair object with forty hairs shows the relationship of the bounding box and random 


offsets to the result hair curves. 


material "hair lambert" 
"lambert" ( 
“Gitfuee”™ 1 .95 .75, 
"lights" ["light-inst"] ) 
end material 


instance "hair-instance" 
geometry 
"hair _geo_ row" ( 


"name" "::hair-1", 
feandiuse"™ .o1, 


"count" 40, 
"pies man” -.7 =.5 =2.8,; 
"bbox max" ot base WD, 
My offset max" .1, 
"Zz offset max" .1, ) 
material "hair _lambert" 
end instance 


Figure 20.49: Beziér curve hairs distributed throughout a bounding box defined by shader parameters 


Increasing the number of hairs and reducing their thickness, we can see the effects of a lighting 
model for hair, implemented in shader hair_color_light, that we'll develop in the next 


section. 
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options "opt" 
object space 
Contrast «<1 «lL «kd 4 
scanline rapid 
shadow on 
shadowmap detail 
samples collect 5 
filter mitchell 

end options 


material "hair_light" 

“hair color light" { 
WLightse" ["light-inst"], 
tditruge" .55 .3 «05, 
"specular" .65 .65 .65, 
"root opacity" .2, 

"tip opacity" .2, 
"exponent" 80 ) 

shadow "hair color light" ( 
"dittuse" .55 «3 .05, 
"root opacity" .05, 
tt1p opacaty" .05, } 

end material 


instance "hair-instance" 
geometry 
"hair geo row" { 
"name" ";:hair-1", 
‘radiue"~ .0025, 
"count" 4000, 
"hbase Mink «i772 =.S.i--2. 
"bbox_max" 7 She SnD; 
"y offset mac" .1, 
ig GEEeer: mac" .1,.°) 
material "hair light" 
end instance 


Figure 20.50: Shader hair_geo_row with 4,000 hairs and the material shader developed in the next section 


The bounding box for the hair defined by hair_geo_row only needs to duplicate the bounding 
box parameters of the shader. 


void hair _ geo row bbox(miObject *obj, void* params) 


{ 


hair _geo row t *p = (hair geo row _t*)params; 


obj ->bbox_max p->bbox_max; 


1 
2 
3 
“: obj->bbox_min p->bbox_min; 
5 
6 


} 


Figure 20.51: Shader source of hair_geo_row (p.547) 


The shader function implements the pattern we’ve been using so far: acquire the parameter values, 
and call miaux_define_hair_object. 
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typedef struct { 
miTag name; 
miInteger count; 
miScalar radius; 
miVector bbox min; 
miVector bbox_ max; 
miScalar y offset_max; 
miScalar z offset max; 
miInteger approximation; 
miInteger degree; 
miInteger random_seed; 
} hair_geo_ row t; 


HH 
FPOWMDAIHUAWNEH 
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miBoolean hair _geo row ( 
miTag *result, miState *state, hair_geo row_t *params 


15 
16 
17 


hair geo row t *p = 

(hair _geo_row_t*) mi_mem_allocate (sizeof (hair_geo_row_t)); 
p->name = *mi_eval_tag(&params->name) ; 
p->count *mi_eval_ integer (&params->count) ; 
p->radius *mi_eval_scalar(&params->radius) ; 
p->bbox_min = *mi_eval_vector (&params->bbox_min) ; 
p->bbox_max *mi_eval_vector (&params->bbox_max) ; 
p->y_offset_ max = *mi_eval_ scalar (&params->y offset max) ; 
p->z_offset_max *mi_eval_scalar(&params->z offset_max) ; 
p->approximation *mi_eval_integer (&params->approximation) ; 
p->degree *mi_ eval integer (&params->degree) ; 
p->random_seed = *mi_eval_integer (&params->random_seed) ; 


eo 
Oo 0 
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miaux_define hair object ( 
p->name, hair _geo_ row bbox, p, result, hair _geo row_callback) ; 


return miTRUE; 


WWW W 
Be WD BR 


Figure 20.52: Source code of shader hair_geo_row (p.547) 


We’ve also seen the basic pattern in the callback function for hair_geo_row before. Most of the 
new complexity comes from the calculation of the randomized offsets to the hair vertices. 
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miBoolean hair _geo row callback(miTag tag, void *ptr) 


{ 


miHair_ list *hair list; 

miGeoIndex *harray; 

miScalar *hair scalars; 

int i, h, per_hair data_count, vertex_count, vertex_size, 
per hair scalar_count, total _scalar_count; 

hair geo row_t *p = (hair_geo_row_t *)ptr; 

miScalar x, y_offset, z_offset, 
yoff max = p->y _offset_max, zoff_max = p->z_offset_max; 


mi _api_ incremental (miTRUE) ; 
miaux define hair object(p->name, hair _geo_row_bbox, p, NULL, NULL); 


hair list = mi_api_ hair begin() ; 

hair _list->approx = p->approximation; 
hair list->degree = p->degree; 

Wi vaps Wear tnro(g, try L}3 

Mi. api baar antoiag, *e*,.°2); 


per hair data_count = 2; /* Radius and random value */ 
vertex count = 
vertex_size = 
per hair scalar count = 

vertex count * vertex_size + per_hair data_count; 
total scalar count = p->count * per hair scalar count; 


hair scalars = mi_api_hair_scalars_begin(total_scalar_count) ; 
mi_srandom(p->random_seed) ; 


= 0; i < p->count; i++) { 
= miaux_random_range(p->bbox_min.x, p->bbox_max.x) ; 
y_offset = miaux_random_range(-yoff max, yoff max) ; 
z offset = miaux_random_range(-zoff max, zoff_max) ; 


*hair scalars++ p->radius; 

*hair scalars++ miaux random _range(0.0, 1.0); 

*hair scalars++ x; 

*hair scalars++ p->bbox_ min.y + yoff max + y_offset; 
*hair_scalars++ p->bbox_min.z + zoff max z offset; 
*hair scalars++ x; 

*hair_scalars++ p->bbox_max. yoff max + y offset; 
*hair scalars++ p->bbox_min. zoff max z offset; 
*hair scalars++ x; 

*hair_scalars++ p->bbox_max. yoff max + y offset; 
*hair scalars++ p->bbox_max. zoff max z offset; 
*hair scalars++ xX; 

*hair scalars++ p->bbox_min.y yoff max y_ottset; 
*hair_scalars++ p->bbox_max.z zoff max 2 O©tset; 


} 


mi_api_hair_scalars_end(total_scalar_count) ; 


harray = mi_api_hair_hairs_ begin(p->count + 1); 
for (h=0; h < p->count + 1; h++) 

harray[h] = h * per _hair_scalar_count; 
mi_api_hair hairs end() ; 


mi_api_ hair _end() ; 
mi_api_object_end() ; 
return miTRUE; 


Figure 20.53: Shader source of hair_geo_row (p.547) 
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In line 18 we specify that a single radius value will be used for each hair, and set that value from 
the radius parameter in line 36 in the creation of the scalar array. In line 19, we define a texture 
value to be part of the scalar array. But note that the number of scalars to use for the texture, the 
final argument, is 1, rather than 4 for the color definition in hair_geo_4v_texture. In line 37, 
a random number between 0.0 and 1.0 is assigned as this single value in the scalar array. This 
random number is then available for use in the material shader, and is constant over the entire 
hair. In the next section, we’ll use that random value to vary the base color of each hair. 


20.9 A basic lighting model for hair 


To create a material shader for hair that takes lighting direction and self-shadowing into account, 
we'll take the phong shader we developed in Section 12.2.1 for our basic structure. 


declare shader 
color “"hair color lLight'™ 1 
color "ambient" default 
eolor "diffuse" default 


color "Specular" default 


scalar "exponent" default 
scalar "root opacity" default 
scalar "tip opacity" default 
scalar "color_variance" default .1, 
array light "lights" ) 

end declare 


Figure 20.54: Shader declaration of hair_color_light (p.549) 


The single scalar we defined as a texture value for each hair will be used to vary the hair color 
from the base color passed to the shader as parameter diffuse. 


void hair_color_ variance ( 
miColor *result, miState *state, struct hair_color_light* params) 


miScalar maximum variance = *mi_eval_scalar(&params->color_ variance) ; 
miScalar color_variance = 


miaux fit (state->tex_list[0].x, 0.0, 1.0, 
1.0 - maximum_variance, 1.0 + maximum_variance) ; 
*result = *mi_eval_ color (&params->diffuse) ; 
miaux_ scale color(result, color_variance) ; 
miaux_clamp_color(result) ; 


Figure 20.55: Shader source of hair_color_light (p.549) 


The opacity of the hair is the average of the root and tip opacities, weighted by the position along 
the hair, represented by state->bary [1]. 
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miScalar hair _alpha(miState *state, struct hair color _light* params) 


{ 


return miaux,_ fit (state-sbary (1), .0.0,. 1.0, 
*mi_eval_ scalar (&params->root_opacity) , 
*mi_eval scalar (&params->tip opacity) ); 


Figure 20.56: Shader source of hair_color_light (p.549) 


The translucency of hair is an important characteristic in its appearance. We’ll use a breakpoint 
function from the chapter on shadows. 


miBoolean hair _shadow(miColor *result, miColor *diffuse, miScalar alpha) 
{ 
miScalar threshold = 0.001; 
miScalar transparency = 1.0 - alpha; 
result->r *= miaux_shadow_breakpoint (diffuse->r, transparency, 
result->g *= miaux_shadow_breakpoint (diffuse->g, transparency, 
result->b *= miaux_shadow_ breakpoint (diffuse->b, transparency, 
if (result->r < threshold && 
result->g < threshold && 
result->b < threshold) 
return miFALSE; 
else 
return miTRUE; 


Figure 20.57: Shader source of hair_color_light (p.549) 


Because we'll be casting shadows through many hairs, we want to terminate shadow casting as 
early as possible. After all the color components of the attenuated value are calculated in lines 5-7, 
we'll terminate shadow casting by return miFALSE if all the components are less than a threshold, 
in this case, 0.001 set in line 3. 


Calculating the diffuse component is typically dependent upon the surface normal. However, 
the simplified geometry of the hair primitive does not define a surface normal vector. We can, 
however, use the tangent vector of the hair, which is stored in state->derivs[0]. The tangent 
is defined at all points along the hair. 


® v2 


Figure 20.58: Tangent to the hair curve at each point available as state->derivs [0] 
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For the calculation of the diffuse and specular components, we’ll pass this tangent vector 
to auxiliary functions modeled on our illumination shaders in Chapter 12. For the diffuse 
component, we subtract the dot product of the hair tangent with the light vector from 1.0; we 
assume that light hitting the hair from any direction illuminates the interior of the hair, so that 
only the angle of the light direction and the hair tangent needs to be considered. 


void miaux_add_ diffuse hair component ( 
miColor *result, miVector *hair tangent, miVector *to_ light, 
miColor *diffuse, miColor *light_color) 


miScalar diffuse factor = 1.0 - fabs(mi_vector dot(hair tangent, to light)); 


1 

2 

3 

- 4 
5 — — — — 
6 miaux_add diffuse _component (result, diffuse factor, diffuse, light color); 
7 


} 


Figure 20.59: Function miaux_add_diffuse_hair_component 


For the specular component, we’ll use a heuristic from a recent paper on hair illumination 
models [Marschner 03]. Given the plane that is normal to the hair tangent, the paper describes a 
prominent specular highlight that occurs when the viewing angle offset from this plane is close 
to the negated value of the incident light angle offset from that plane [Marschner 03, page 783; 
see diagram on page 782 for notation]. 


void miaux_add_ specular _ hair component ( 
miColor *result, miVector *hair_tangent, miVector *to light, 
miVector *to camera, 
miColor *specular, miColor *light_ color) 


miScalar light_angle = acos(mi_vector_ dot (hair_tangent, to_light)); 
miScalar view_angle = acos(mi_vector dot (hair tangent, to camera) ) ; 
miScalar sum = light_angle + view angle; 

miScalar specular factor = fabs(M_PI_2 - fmod(sum, M_PI)) / M PI _ 2; 


result->r += specular factor * specular->r * light -color->r; 
result->g += specular _ factor * specular->sg * light _color->g; 
result->b += specular factor * specular->b * light color->b; 


Figure 20.60: Function miaux_add_specular_hair_component 


Finally, we want to blend in the background with the hair color as calculated from the diffuse 
and specular components. 


void miaux_add_transparent_hair_component (miColor *result, miState *state) 
miColor background_color; 
mi_trace_ transparent (&background_ color, state) ; 
if (result->a == 0) { 
miaux_ opacity set _channels(state, 0.0); 


miaux_copy_color(result, &background_color) ; 
} else { 
miaux opacity set _channels(state, result->a) ; 
miaux blend _colors(result, result, &background_color, result->a) ; 


Figure 20.61: Function miaux_add_transparent_hair_component 
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These component functions allow shader hair_color_light to use the illumination shader 
structure we’ve already developed in Chapter 12, in which a loop through all the lights contains 
an inner loop of lighting samples. 


1 struct hair color light { 
2 miColor ambient; 
3 miColor diffuse; 
4 miColor specular; 
5 miScalar exponent; 
6 miScalar root opacity; 
7 miScalar tip opacity; 
8 miScalar color variance; 
9 int 1 Lagne3 
10 int nm light» 
a2 miTag light [1]; 
12 }; 
a3 
14 miBoolean hair_color_light ( 
15 miColor *result, miState *state, struct hair _ color light *params ) 
16.. 4 
17 int 1, light_count, light sample count; 
18 miColor diffuse, sum, light color, *specular; 
is miVector direction toward light, to camera; 
20 miScalar dot_nl, alpha; 
21 miTag *light; 
a2 miVector hair tangent = state->derivs [0]; 
23 miVector original normal = state->normal; 
24 
25 hair color variance (&diffuse, state, params) ; 
26 alpha = hair _alpha(state, params) ; 
a 
28 if (state->type == miRAY_ SHADOW) 
29 return hair shadow(result, &diffuse, alpha) ; 
30 
S1 state->normal.x = state->normal.y = state->normal.z = 0.0f; 
32 to camera = state->dir; 
33 mi vector neg(&to camera) ; 
34 mi vector normalize(&hair tangent) ; 
35 
36 specular = mi_eval_ color (&params->specular) ; 
37 *result = *mi_eval_color(&params->ambient) ; 
38 result->a = alpha; 
39 
40 miaux_ light array(&light, &light count, state, 
Al &params->i light, &params->n_light, params->light) ; 
42 
43 for (i = 0; i < light count; i++, light++) { 
44 miaux_set_channels(&sum, 0); 
45 light _sample_ count = 0; 
46 while (mi_sample light (&light_ color, &direction_toward_light, &édot_nl, 
7 state, *light, &light sample count)) { 
48 miaux_add diffuse hair component ( 
49 &sum, &hair_ tangent, &direction_toward_light, 
50 &diffuse, &light_color) ; 
Si miaux_add_ specular hair component ( 
52 &sum, &hair_ tangent, &direction_ toward light, &to_camera, 
53 specular, &light color) ; 
54 } 
55 if (light _sample_count) 
56 miaux_add_ scaled _color(result, &sum, 1.0/light sample count) ; 
57 } 
58 state->normal = original normal; 
59 if (result-sa < 0.999) 
60 miaux_add_ transparent hair component (result, state) ; 
61 return miTRUE; 
62 } 


Figure 20.62: Source code of shader hair_color_light (p.549) 
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Because of the optimized hair geometry, we need to redefine the state->normal to a null vector 
in line 31 for the calculation of the light color in the mi_sample_light loop in lines 46-54. 
However, we need to restore the state->normal value (done in line 58 from the value saved in 
line 31) before the shader exits. By testing for a shadow ray in line 28, we can use this shader for 
both the material and shadow shaders. (Nulling the state->normal vector in line 31 is deferred 
until after the exit that occurs when the shader is used for shadows.) 


options "opt" 
object space 
CONETR@ST «Lb «wt «bt 1 
scanline rapid 
shadow on 
shadowmap detail 
samples collect 5 
filter mitchell 

end options 


material "hair light" 

(air. color laghk™ { 
Wlights" [*®light-inet"], 
"Aiffuse™ Ss. 35. 208; 
"specular”™ .65...65 .66;, 
“Poot. opgeLty" 2, 
"tip-opacgity” .2, 
"exponent" 80 ) 


shadow “hair color light" { 


"diffuse" 

"root opacity" 

"tip opacity" 
end material 


OG, 5 de = ee 
MS, 
Vs, ) 


instance "hair-instance" 
geometry 
"hair _geo_ row" ( 
"name" ":;:hair-1", 
"radius" .0025, 
"count" 4000, 
"bDbex min" -.7 =.,5 =2. 
"bbox_max" <<? dee DO, 
"y Offset max" .1, 
ty oOfftset_max" .1, ) 
material "hair light" 
end instance 


Figure 20.63: Defining other rendering modes in the options block for hair rendering 


Rendering many hairs can be greatly accelerated by using mental ray’s rasterizer mode. Using 
detail shadow maps is also desirable when rendering of large numbers of transparent hairs. These 
various modes can be defined on the command line or specified as statements in the options 
block in the scene file, as in Figure 20.63. 


Though we are rendering many hairs, the basic structure of the hair geometry shader has remained 
the same from our initial single hair examples. A shader like hair_geo_row may not be general 
enough to be appropriate in a production context, but it is very useful as a test bed for developing 
more complex hair illumination shaders like hair_color_light. 


Prog 14, 1.8. Light Sources 


Prog 155, 2.7.13. Subdivision 
Surface Geometry 


Prog 91, 2.7.1.6. Shadows 


Prog 93, 2.7.1.7. Rendering 
Algorithms 
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20.10 The hair primitive as a general modeling tool 


The word “hair” can lead us to think that only hair-like objects can be created with the hair 
primitive. Though we can begin to see artifacts at larger scales of the geometric optimizations 
that make hairs efficient to render, we can still model a wide variety of structures using it. 


For example, the creation of spiral hair shapes with large hair radii can produce plant-like 
objects. 


material "hair light" 

"hair color light" ( 
"lights" [*light-inst"] , 
"diffuse" .4 .5 .3; 
Menecular” .6 .6 3, 
"root opacity". 1, 

VEtD opacity 9, ) 
shadow "hair color light" ( 
"diffuse" .45 .5 .4, 
"root opacity" 1, 
"ip opacity” 5°) 
end material 


instance "hair-instance" 
geometry 
"“Halr geoveurl”. { 
"name" “: shair”, 
"counc”. 200, 
"root. radius" .04, 
"Cip radius" .0001, 
“Senter” 0 .3 0, 
"length min" .6, 
"length max" .85, 
‘Spare: vurnes min” .5, 
‘spiral turns thax”.1.5, 
"spiral radius min” .02, 
"spiral radius max" .03 ) 
material “hair light" 
end instance 


Figure 20.64: Plant-like shapes using the hair primitive 


We’ll define a geometry shader called hair_geo_cur1 that will parameterize the various spiral 
hair components that radiate outward from a given center. 


declare shader 
geometry "hair geo curl" ( 

string "name", 
integer "count" default 1, 
scalar "root_radius" default .01, 
scalar "tip radius" default .0001, 
vector "center" default 0 0 0, 
scalar "length min" default .5, 
scalar "length max" default 1, 
scalar "spiral turns min" default 2, 
scalar "Spiral _turns_max" default 3, 
scalar "spiral radius min" default .01, 
scalar "spiral radius max" default .03, 
scalar "segment length" default .05, 
integer "random_seed" default 1955 ) 

end declare 


Figure 20.65: Shader declaration of hair_geo_curl (p.552) 


20.10 The hair primitive as a general modeling tool 


In the same manner as the previous hair shaders, we need to define a bounding box function. 
object and the maximum length defined as parameters, the bounding box 


Given the center of the 


is the full extent from the center by that maximum length. 


{ 


a 
2 
3 
4 
5 
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8 
9 
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1 


} 


The hair_geo_curl shader function also follows the same pattern as the previous hair 


shaders. 


miScalar 
miScalar 
miVector 
miScalar 
miScalar 
miScalar 
miScalar 
miScalar 
miScalar 
miScalar 
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void hair _geo_ curl bbox(miObject *obj, void* params) 


hair _geo curl t (hair _geo curl t*) params; 
obj ->bbox_min.x = p->center. p->length_ max; 
obj ->bbox_min. p->center. p->length_ max; 
obj ->bbox_min. p->center. p->length_max; 
obj ->bbox_max. p-SCencer. p->length_max; 
obj ->bbox_max. p->center. p->length_max; 
obj ->bbox_max. p->center. p->length_ max; 


Figure 20.66: Shader source of hair_geo_curl (p.552) 


typedef struct { 
miTag name; 
miInteger count; 


root_radius; 

tip radius; 
center; 
length_min; 
length_max; 
spiral_turns_min; 
spiral _turns_max; 
spiral _radius_ min; 
spiral radius max; 
segment length; 


miInteger random_seed; 


} hair_geo curl t; 
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miBoolean hair _geo_curl ( 


{ 


p->name 
p->count 
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p->spiral_turns_max *mi_eval_ scalar (&params->spiral_turns_max 
p->spiral_radius_min *mi_eval_scalar(&params->spiral radius _mi 
p->spiral radius_max *mi_eval_scalar(&params->spiral_ radius_max 
p->segment_ length = *mi_eval_ scalar (&params->segment_length) ; 
p->random_seed = *mi_eval_integer (&params->random_seed) ; 


miTag *result, miState *state, hair_geo_ curl t *params ) 


hair_geo curl t *p = 
(hair _geo_curl_t*)mi_mem_allocate(sizeof (hair geo curl t)); 


= *mi_eval_tag(&params->name) ; 
= *mi_eval_integer (&params->count) ; 


p->root_radius *mi_eval_ scalar (&params->root_radius) ; 
p->tip_ radius *mi_eval_ scalar (&params->tip_ radius) ; 
p->center *mi_eval_ vector (&params->center) ; 
p->length_min = *mi_eval_scalar(&params->length_min) ; 
p->length_max *mi_eval_ scalar (&params->length_max) ; 
p->spiral turns min *mi_eval_scalar(&params->spiral turns _ min 
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miaux define hair object ( 
p->name, hair _geo_ curl bbox, p, result, hair_geo_curl_callback) ; 


return miTRUE; 


Figure 20.67: Source code of shader hair_geo_curl (p.552) 
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The callback function for hair_geo_cur1 will define the vertices and radii for the hairs that curl 
from the center point. To define the hair directions, we will distribute the hair endpoints randomly 
over the surface of a sphere, defined by the center and radius parameters to the shader. 


void miaux_random_point_on_sphere ( 


{ 


miVector *result, miVector *center, miScalar radius) 


miMatrix transform; 
result->x = radius; 
result->y = result->z = 0.0; 
mi matrix rotate(transform, 0, 
miaux_ random _range(0, M PI * 2), 
miaux_random_range(0, M_PI * 2)); 
mi vector _transform(result, result, transform) ; 
mi_vector_add(result, result, center) ; 


Figure 20.68: Function miaux_random_point_on_sphere 


Each radiating hair may have a different number of vertices, given the constant segment length 
parameter but a varying total length for each hair. When we define the hair arrays, however, we 
need to know in advance the total number of hair scalars to be used for the hair list. To solve this 
problem, we'll define an array of structs in which we store information about each hair. As we 
construct this array, we can also keep track of the total number of vertices required, and use this 
information to initialize the hair arrays. We then use the array of structs to define the data for 
the hair arrays themselves. 


typedef struct { 
miVector hair end; 
int vertex_count; 


miScalar turns; 
miScalar spiral radius; 
} hair_spec t; 


Figure 20.69: Source code of struct hair_spec_t (p.552) 


The data in the array of hair_spec_t structs is created as random values within the ranges 
specified in the shader parameters. 
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int create hair specifications ( 


{ 


hair spec’ t **hair specs, hair geo curl, t. *p) 


float pi. B= M BL * 2.0; 
int scalars per vertex = 4, total scalar count = 0, i; 
*hair specs = 
(hair _spec_t*)mi_mem_allocate(p->count * sizeof (hair spec t)); 
for (i = 0; i < p->count; i++) { 
miScalar distance, length; 
hair spec_t.*spec = &((*hair specs) [1]); 
spec->turns = 
miaux_random_range(p->spiral_ turns min, p->spiral_turns_max) ; 
spec->spiral radius = 
miaux_random_range(p->spiral_radius_ min, p->spiral radius_max) ; 
distance = miaux_random_range(p->length_ min, p->length_max) ; 
length = distance + pi 2 * -spec->spiral radius * spec->turns; 
miaux_random_point_on_sphere ( 
&(spec-shair_end), &p->center, distance) ; 
spec->vertex count = (int) (ceil(length / p->segment length) ) ; 
Cotal scalar count +=. spec-svertex count * scalars per vertex; 


} 


return total scalar count; 


Figure 20.70: Shader source of hair_geo_curl (p.552) 


Function create_hair_specifications both fills the hair_specs array passed as an argument 
with a set of structs, but also returns the number of scalars as the result of the function. This 
returned value will be used in the shader callback as the argument when the API function creates 
the scalar array. 


Now that we have defined the parameters for each of the hair spirals that will radiate from the 
center, we need to create the spirals themselves. For each spiral axis, we'll create a point that is 
some distance away from the base point of the axis, and then rotate that point around the axis, 
moving it along the axis to create the spiral. 


First, given a vector, we define a point some distance away from the origin and perpendicular to 
that vector. 


void miaux_perpendicular point (miVector *result, miVector *v, float distance) 


result->x = -v->y; 
result->y = v->x; 


result-2z = 0; 
mi ‘vector normalize (result) ; 
mi vector mul (result, distance) ; 


Figure 20.71: Function miaux_perpendicular_point 


We also need to define intermediate points along the axis that will serve as the positions to which 
we ll translate the spiral point. 
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void miaux_point_ between ( 


{ 


miVector *result, miVector *u, miVector *v, float fraction) 


result->x = miaux fit(fraction, 0, u->X, V->xX); 
result->y miaux fit(fraction, 0, u->y, vV->y); 
result->z = miaux_fit(fraction, 0, U->Z, V->Z); 


Figure 20.72: Function miaux_point_between 


Now we can define the series of vertices for the spiral by creating the spiral axis from the starting 
and ending point parameters. 


void miaux_hair_ spiral ( 
miScalar** scalar _array, miVector *start_ point, miVector *end_point, 
float turns, int point count, float angle offset, float spiral radius, 
miScalar root_radius, miScalar tip radius) 


ete | 


miVector base point, spiral axis, spiral_point; 

miVector axis point; 

miMatrix matrix; 

float angle, pi_2 = 2 * M_PI, max_index = point_count - 1; 
int i; 


DAANAHDUHI PWN KH 


mi vector sub(&spiral axis, end point, start point) ; 
mi_vector_normalize(&spiral_ axis) ; 
miaux_ perpendicular point (&axis point, &spiral_axis, spiral radius) ; 


for (i = 0; i < point count; i++) { 
float fraction = i / max_index; 
miaux_point between(&base point, start_point, end_point, fraction) ; 
angle = angle offset + fraction * turns * pi 2; 
mi_matrix_rotate_axis(matrix, &spiral_axis, angle) ; 
mi_point_transform(&spiral point, &axis_ point, matrix) ; 
mi vector add(&spiral point, &spiral point, &base point) ; 


*(*scalar_array)++ = spiral _point.x; 
*(*scalar_ array) ++ spiral point.y; 
*(*scalar_ array) ++ spiral point.z; 
*(*scalar_ array) ++ 
miaux_ fit _clamp(i, 0, max_index, root radius, tip radius) ; 


Figure 20.73: Function miaux_hair_spiral 


Lines 12-13 define the spiral axis, which is used in line 14 to create the point that will be rotated 
around it. The loop in lines 16-29 determines the incremental position along the axis in line 18 
and the current spiral angle in line 19. From the initial point, a new point is created in line 21 


with the given rotation around the axis and then translated into position along the spiral axis in 
line 22. 


In lines 24-28 the hair scalar array passed as an argument is filled with the vertex components 
and the radius value, calculated as the average of the root and tip radius parameters weighted by 
the distance along the spiral. 
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The callback function for hair_geo_cur1 creates the array of hair_spec_t structs to define the 
hair scalar array. 


miBoolean hair_geo_ curl _callback(miTag tag, void *ptr) 
{ 

miHair list *hair; 

miGeoIndex *harray; 

hair geo curl t *p = (hair_geo_ curl t*)ptr; 

hair _spec_t *hair_specs; 

int i, total _scalar_count, hair_array_ position; 

miScalar *hair scalars; 


mi_srandom(p->random_seed) ; 

mi_api_incremental (miTRUE) ; 

miaux_define hair object (p->name, hair_geo curl _bbox, p, NULL, NULL); 
hair = mi_api_hair begin()j; 

hair->approx = hair->degree = 

Ml @pi, Wass tproll,, "x", Li; 


total scalar_count = create hair specifications (&hair specs, p); 
hair _ scalars = mi_api_hair_scalars_ begin(total_scalar_count) ; 


for (i = 0; i < p->count; i++) { 
Float angle offset = miaux_random_range(0, M PI * 2); 
miaux hair spiral ( 
&hair scalars, &p->center, &hair_specs[i] .hair_end, 
hair specs[i].turns, hair specs[i].vertex count, angle offset, 
hair _specs[i].spiral radius, p->root_radius, p->tip radius) ; 


} 


mi_api_hair_ scalars _end(total_ scalar_count) ; 


harray = mi_api_hair_ hairs begin(p->count + 1); 
hair _array_position = 0; 
for (i = 0; i < p->count + 1; i++) { 
harray[i] = hair_array_ position; 
if ({i-< p-scount) 
hair_array_ position += hair _specs[i].vertex_count * 4; 


} 


mi_api_hair_hairs_end()j; 


mi_api_ hair _end(); 
mi_api_object_end()j; 
mi_mem_release (hair specs) ; 


return miTRUE; 


Figure 20.74: Shader source of hair_geo_curl (p.552) 


In line 17, function create_hair_specifications creates the hair_specs array and sets the 
value of total_scalar_count. This value can then be used in line 18 to initialize the hair scalar 
array. In lines 20-26 the hair scalar array is filled with the values defined by hair_specs as well 
as by the various parameters to the shader. 


In line 34, the individual vertex count in each element of the hair_specs array is used for the 
values of the hair index array. The loop executes for an additional iteration so that the final 
position in the hair index array points one element past the end of the hair scalar array. This 
requires the conditional in line 33 because there are only p->count number of elements in the 
hair_specs array. 
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Figure 20.75 shows another example of shader hair_geo_cur1 using smaller radii and many more 
hairs. 


options "opt" 
object space 
contrast .1.1.4141 
scanline rapid 
shadow on 
shadowmap detail 
samples collect 5 
filter mitchell 4 
end options 


material “hair light" 

"hair color light” ( 
"lights" ["light-inst"], 
"diffuse" .4 .5 .3, 
"Specular" .6 .6 .3, 
"Toot ‘opacity™ 1, 

'"Cip opacity" .9, } 
shadow "hair color light" ( 
"AQiLause” 345° .5 “<4, 


"root opacity" 1, 
"Cap opacicy” 5 ) 
end material 


instance "hair-instance" 
geometry 
"hair geo curl" ( 
"name" "::shair", 
"count" 4000, 
"center" 0 .3 0, 
"root radius" .006, 
"Clip radius" ,001, 
"length _min" .6, 
Wlengen max" .85, 
"Spiral turns min" 1, 
"Spiral turns max" 2, 
"Spiral radius min" .04, 
"Spiral radius max" .06 ) 
material "hair light" 
end instance 


Figure 20.75: Increasing the number of hairs in shader hair_geo_curl 


One method of designing geometry shaders is to think of the class of objects that the shader 
defines, with the different instances of the class varying based upon parameter values. The 
more fully we parameterize the shaders, the larger and more variable these object classes can 
become. 


20.11 The hair primitive and particle systems 


The rendering efficiency of the hair primitive makes it a useful way to render particle systems, 
in which a simple representation of many small objects is used to create effects like blowing 
dust, fire, and water spray. The representation of particle data varies widely from application to 
application. To demonstrate the use of hair in a particle system, we’ll define a file format (HPD, 
for “hair particle data”), and then develop a shader that reads that file to create hair objects. 


Figure 20.76 shows the structure of our example of possible particle data file we'll use as input in 
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the shader. The file is in ASCII format, with numbers separated by whitespace characters. The 
newlines allow the file to be more easily examined in a text editor, but are ignored during parsing 
with C’s fscanf library function. 


Number of particles and vertices hair count vertex count 
catatorasinglepatcte | [age ][ om oo 


One line for each particle 


Figure 20.76: File format for particle system data as input to hair geometry shader 


You can tell that I’ve designed this format to facilitate the creation of hair particle data. With 
the total number of hairs and vertices from the first line, the size of the hair scalar array can 
be calculated, given the extra data the shader may associate with the particles for their radius, 
color or other information. The bounding box data on the second line can also easily be read 
when creating the placeholder object in the shader function. For each hair, the “age” value allows 
particle effects like the change of color of sparks over time. The second item on each particle line, 
“count,” determines how many vertices are used by that particle, and allow particles to vary in 
the number of vertices used to define the corresponding hair. 


instance "explosion-instance" 

geometry "hair geo datafile" ( 
‘yadtue" 9001, 
"particle filename" "explosion.hpd" ) 

material "hair light" 

transform 
a 29 OD 
Or = 8a OQ 
)-. 0-| 2& 20 
Q .25 .4 


end instance 


Figure 20.77: Hair used as the geometric primitive to render a particle system 


Shader hair_geo_datafile only defines the radius of the hairs as a parameter; the shader function 
will convert the data from the file 
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declare shader 
geometry "hair geo datafile" ( 
string "name", 


scalar "radius" default .1, 
string "particle filename" ) 
end declare 


Figure 20.78: Shader declaration of hair_geo_datafile (p.555) 


To use the bounding box mechanism we’ve developed for the previous hair shaders, we need to 
specify the bounding box in the shader, before we actually read the data to create the hairs in the 
callback function. We first define a general function in the miaux library to read the bounding 


box from an HPD file. 


void miaux_ hair data file bounding _ box ( 
char* filename, 
float *xmin, float *ymin, float *zmin, 
Float *xmax, float *ymax, float *zmax) 


int hair_count, data_count; 

FILE* fp = fopen(filename, "r") ; 

fscanf(fp, "td td", &hair count, &data_count); /* Ignore. */ 
fscanf(fp, "Sf Sf Sf S£ £ S£ ", xmin, ymin, zmin, xmax, ymax, zmax) ; 
Eclose (fp) ; 


Figure 20.79: Function miaux_hair_data_file_bounding_box 


We can extract the bounding box data from the file by reading but ignoring the initial two data 
items in line 8, and then reading the bounding box data. We close the file in line 10, and will 
reopen it when we need the vertex data in the callback function. It is slightly inefficient to open 
the particle data file twice, but the time it takes is insignificant compared to the much longer time 
required by rendering even the simplest particle data set. 


Now we'll use this general function to make a bounding box function with the required argument 
prototype to use in hair_geo_datafile. Extracting the general operation into a separate function 
will simplify the creation of other geometry shaders that use the HPD format. 


void hair _ geo datafile bbox(miObject *obj, void* params) 
{ 
hair geo datafile t *hairdata = (hair_geo datafile t*)params; 
char* particle filename; 
particle filename = 
miaux_tag_to_string(hairdata->particle filename, NULL) ; 


if (particle filename == NULL) 
mi_fatal("Particle filename required for hair_geo datafile.") ; 
miaux_hair_ data_file bounding_box( 
particle filename, 
&0bj->bbox_min.x, &obj->bbox_min.y, &obj->bbox_min.z, 
&O0bj->bbox_max.x, &obj->bbox_max.y, &obj->bbox_max.z) ; 


Figure 20.80: Shader source of hair_geo_datafile (p.555) 
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With this bounding box function, we can now define the main shader function for 
hair_geo_datafile. 


typedef struct { 

miTag name; 

miScalar radius; 

miTag particle filename; 
} hair_geo datafile t; 


miBoolean hair_geo datafile ( 
miTag *result, miState *state, hair _ geo datafile t *params ) 


hair _geo datafile t *hairdata = 

(hair _geo datafile t*)mi_mem_allocate(sizeof (hair _geo datafile t)); 
hairdata->radius = *mi_eval_scalar(&params->radius) ; 
hairdata->particle filename = *mi_eval_tag(&params->particle filename) ; 


miaux define hair_object ( 
hairdata->name, hair_geo datafile bbox, hairdata, result, 


hair _geo datafile callback) ; 


return miTRUE; 


Figure 20.81: Source code of shader hair_geo_datafile (p.555) 


Notice that we’re able to use the same pattern, even though the actions of the callback will be 
quite different than the other shaders we’ve written. First we’ll define another general function 
in the miaux library to read the HPD file and create the hair arrays. 
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void miaux_ read hair data file(char* filename, miScalar radius) 
{ 
int vertex count, total vertex count, hair_scalar_size, vertex_total = 0, 
index array size, v, *hair indices, *hi, hair_count, per_hair_ scalars; 
float xmin, ymin, zmin, xmax, ymax, zmax, age; 
miScalar coord, *hair_ scalars; 
miGeoIndex *harray; 
FILE *fp; 
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fp = fopen(filename, "r") ; 
Escanf(fp, "sd $d ", &hair_ count, &total vertex_count) ; 
fscanf(fp, "sf sf t£ Sf SF Sf ", 
&xmin, &ymin, &zmin, &xmax, &ymax, &zmax) ; 
mi _progress("particle bounding box: %f *f sf sf sf sf ", 
xmin, ymin, zmin, xmax, ymax, zmax) ; 
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per hair scalars = 2; 
til api hair into(d, “2", 1); 
mi_api_ hair info(0, ‘t’, 1); 


hair scalar_size = hair _ count * per hair scalars + total _vertex_count * 3; 
hair _scalars = mi_api_hair_ scalars _begin(hair_scalar_size) ; 


16 
17 
18 
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index _array_size = 1 + hair_count; 

hi = hair _ indices = (int*)mi_mem_allocate(sizeof (int) * index_array_size) ; 
*hi++ = 0; 

vertex total = 0; 


NN 
O1 & 
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while (!feof(fp)) { 

*hair_scalars++ radius; 

fscanf(fp, "% &age) ; 

*hair scalars++ age; 

Fscanf (fp, "td ", &vertex count) ; 

for (v = 0; v < vertex count * 3; v++) { 
fscant (fp, "t£ ", &coord) ; 
*hair scalars++ = coord; 

} 

vertex total += vertex _count * 3 + per_hair_ scalars; 

*hi++ = vertex_total; 


WWW WW WW WW WwW 
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} 

mi_api_hair_ scalars _end(hair_scalar_size) ; 

harray = mi_api_hair hairs _begin(index_array_size) ; 

memcpy (harray, hair_indices, index_array_size * sizeof (int) ); 
mi_api_hair hairs end() ; 


Pop op BB 
UB WNYRO 


Figure 20.82: Function miaux_read_hair_data_file 


The lines 10-13 we open the HPD file, and read the count and bounding box data. At this 
point, we no longer need the bounding box information, but it may be useful to display it during 
rendering, as in lines 14-15. 


The HPD file includes an extra data value for the “age” of the particle. This age information 
and the radius value are stored for each hair in addition to the vertex information as specified by 
mi_api_hair_info in lines 18-19. Taking the age and radius into account, we can determine the 


total size of the hair scalar array, and use this value to initialize the hair scalar array as usual in 
line 22. 


However, we treat the hair index array differently in this shader. Rather than parsing the file 
twice, we construct an array that will contain hair index data in line 25 and set the value of the 
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array’s elements in line 39 by keeping track of the position of each hair through the vertex_total 
variable updated in line 38. When all vertices have been processed, we then copy the array of 
hair indices to the address created by the API function in line 43. 


The callback function calls miaux_read_hair_data_file. By changing this internal utility 
function, this callback can serve as a template for other particle system shaders. 


miBoolean hair geo datafile callback(miTag tag, void *ptr) 
{ 
miHair list *hair; 
hair geo datafile t *hairdata = (hair_geo datafile. t *) ptr; 


mi_api_ incremental (miTRUE) ; 
miaux define hair object ( 
hairdata->name, hair geo datafile bbox, hairdata, NULL, NULL) ; 
hair = mi_api_hair_begin() ; 
hair->approx = hair->degree = 1; 


1 
2 
2 
4 
5 
6 
7 
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miaux_read hair data file ( 
miaux tag to string(hairdata->particle filename, NULL), 
hairdata->radius) ; 

mi_api hair end(); 

mi_api object _end(); 

return miTRUE; 


Figure 20.83: Shader source of hair_geo_datafile (p.555) 


Increasing the number of particles and decreasing their size, we can create a variety of effects 
with the same data file format. 
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options "opt" 
object space 
Centrase. .d. ad, adh ft 
scanline rapid 
shadow on 
shadowmap detail 
samples collect 5 
filter mitchell 4 
end options 


material "hair light" 

"hair color light" ( 
"Lighnte*® T*Light-inst"], 
"diffuse" .6 .6 .8, 
"enecular™ .2 «2 «2, 
‘Toow apacity” ‘1, 

"Cip Opacity” 0 ) 


shadow "hair color light" ( 
"diffuse" 6 +~6°.8, 
"root opacity” 1, 
"tip opacity" 0 ) 
end material 


instance "fountain-instance" 
geometry "hair geo datafile" ( 
‘radius .002, 
"Darticle filename" "fountain.hpd" ) 
material "hair light" 
transform 
.5 & 0 DO 
) «5-09 
00 .5 0 
uaz fl 
end instance 


Figure 20.84: Simulating water droplets with shorter hair lengths 


Storing additional information from the particle system will allow for other possibilities in the 
material shader. For example, an orientation vector stored for each particle and which rotates 
throughout the course of the animation could be used to calculate a specular highlight that could 
simulate the effect of light sparkling on water. 


20.12 Particle system data and dynamic rendering effects 


For particle effects like sparks from a fire, the appearance of a particle will be dependent upon its 
“age,” or how long it has existed in the animation since its “birth.” In section 20.11 we ignored 
the age parameter included as part of the HPD file format. In this section, we’ll use the age 
parameter to define the particle’s color, changing during its lifetime from white, through yellow, 
to red and finally to black, to roughly simulate the sparks from a fire. 


declare shader 
color "“haiz color Fire" { 


color "transparency" default 0.5 0.5 0.5 ) 
end declare 


Figure 20.85: Shader declaration of hair_color_fire (p.556) 
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Particle color will be defined in the shader function itself as a color ramp, or a continuous sequence 
of colors mapped to the particle’s age as it changes from 0.0 (birth) to 1.0 (death). To simplify 
a color ramp based on a series of points in time, we’ll define an auxiliary function that behaves 
much like miaux_fit, but for values of type miColor. 


void miaux_color fit(miColor *result, 
miScalar f, miScalar start, miScalar end, 
miColor *start_color, miColor *end_color) 


result->r mieux fat(f, start, end, start color~er, end_color->r) ; 
result->g miaux fit(f, atart, end, ‘start color-sg, end color~=sg) ; 
result->b miaux fit(f, start, end, start_color->sb, end_color-=sb) ; 


Figure 20.86: Function miaux_color_fit 


We’ll also arbitrarily define a transparency value for the particles as a parameter to the shader. 
The animation system that generates the particle data may have an accurate estimate for the 
effective “transparency” due to motion blur, but for this simple example we’ll just define a 
transparency value explicitly. Since larger numbers of hairs are more efficiently rendered by 
using the rasterizer (see page 319), we'll need to set the opacity value that the rasterizer requires. 
We'll wrap up all these actions related to transparency calculation in a single utility function, 
miaux_blend_transparency. 


void miaux_blend_transparency(miColor *result, 
miState *state, miColor *transparency) 


miColor opacity, background; 
miaux invert channels(&opacity, transparency) ; 


mi opacity set(state, &opacity) ; 

if (!miaux_all_ channels equal(transparency, 1.0)) { 
mi trace transparent (&background, state) ; 
miaux_blend_channels(result, &background, &opacity) ; 


Figure 20.87: Function miaux_blend_transparency 


Now in the shader hair_color_fire, each particle’s appearance is defined by using the particle’s 
age, varying from 0.0 to 1.0, as a mapping to a color in the ramp. 
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struct hair color fire { 
miColor transparency; 


miBoolean hair color fire ( 
miColor *result, miState *state, struct hair color fire *params ) 
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miScalar keys [6] 
miColor colors [6] 
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miColor *transparency = mi_eval_ color(&params->transparency) ; 
miScalar age = state->tex list[0] .x; 
int i; 
for (i = 4; i >=0; i--) { 
if (age >= keys[i]) { 
miaux_color fit(result, age, 
keys[i], keys[i+1], &colors[i], &colors[i+1]) ; 
break; 


} 


} 


miaux_ blend transparency (result, state, transparency) ; 


return miTRUE; 


Figure 20.88: Shader source of hair_color_fire (p.556) 


The keys array in line 8 defines the position in the 0.0 to 1.0 range that the corresponding color 
in the colors array in lines 9-14 should be placed. The value of age in line 16 is derived from the 
scalar assigned along with the particle radius in miaux_read_hair_data_file on page 330. The 
texture values for hairs are stored in the texture coordinate list state->tex_list. Since the age 
was stored as ascalar value in the texture coordinate list, we reference it as state->tex_list [0] .x 
in line 16. 


The six colors in the colors array in lines 9-14 define five linear color ramps, a ramp from the 
first color to the second, from the second to the third, and so forth. The loop in lines 18-24 
iterates through the keys on line 8 from the highest age value (1.0) to the lowest (0.0) so that we 
can break out of the loop as soon the containing range for the age value is found. 
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options "opt" 
object space 
Gomtrest .1 .i1 «l i 
scanline rapid 
samples collect 3 
filter gauss 3 3 
dither oft 

end options 


material "spark" 


“Hair color fire" { 
"transparency" .1 .1 .1 ) 
end material 


instance "fire-instance" 
geometry "hair geo datafile" ( 
"radius" .03, 
"Darticle filename" "fire.0055.hpd" ) 
material "spark" 
end instance 


Figure 20.89: Modifying hair particle colors based on the age of the particle 


Shader hair_color_fire creates a specific color ramp that defines particle colors based on their 
age. This color ramp is hard-coded into the shader and cannot be changed when the shader is 
called as part of a material. Furthermore, the color value of particles with the same age must be 
inefficiently recalculated. In the next chapter we'll look at ways we can both parameterize the 
data used in a shader as well as make the calculation of that data more efficient through look-up 
table structures. 
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Part 5: Space 


Chapter 21 


The environment of the scene 


In Chapter 14 we used an environment shader to specify a color for reflecting rays that left the 
scene without striking any other objects. Environment shaders simply return a color, but in this 
chapter we will also provide optional initialization and cleanup functions that will assist in the 
environment shader’s calculations. These optional shader functions can be defined for any shader 


type. 


21.1. Asingle color for the environment 


Without an environment shader, any ray that leaves the scene or exceeds the trace depth produces 
black (all color channels are zero). By specifying a shader in an environment statement in the 
camera, the color calculated by this shader is used instead of black. 


With shader one_color from Chapter 5, we can define a single color in the camera object to be 
used for the environment. 


camera "cam" 
outpuc "rgba" "tit" "environnent_1.,tif" 
rocal 1.5 
aperture 1:5 
aspect 1 


resolution 300 300 
environment 
‘one ‘eoior™’ /{ 
leoior® . i 
end camera 


. 


Figure 21.1: Shader one_color attached to the camera as an environment shader 


Prog 256, 3.12. Environment 
Shaders 


Prog 403, 3.27. Initialization 
and Cleanup 


Prog 91, 2.7.1.5. Trace Depth 


Prog 111, 2.7.2.3. Other 
Camera Statements 


Prog 204, 3.4.3. Rays 
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The miState pointer provided to the environment shader describes the state of the ray that left 
the scene or that would cause the trace depth to be exceeded. We’ll use this state to define a ramp 
of colors to simulate a very simple landscape and sky. 


21.2 Defining a color ramp 


To create a color ramp, a smoothly varying sequence of colors that corresponds to the apparent 
altitude in a scene, we will map the orientation of the eye ray or reflection vector to a set of color 
values. 


Ray directions ==> __ Color ramp 


Figure 21.2: Mapping altitude to positions in a ramp of colors 


Utility function miaux_altitude converts the vertical orientation of a vector to a scalar value 
between 0.0 (straight down) and 1.0 (straight up). 


float miaux_altitude(miState *state) 


{ 


miVector ray; 


mi_vector_ normalize (&ray) ; 


1 

2 

3 

4 mi_vector_to_world(state, &ray, &state->dir) ; 
5 

6 return miaux_fit(asin(ray.y), -M_PI_2, M_ PI_2, 
v 


} 


Figure 21.3: Function miaux_altitude 


The direction of the ray, state->dir, is the basis for the color ramp lookup function. By 
normalizing the direction ray in line 5 we know that the y component of the vector will vary 
from -1.0 to 1.0. The arcsine of y will therefore vary from —7/2 to 7/2 radians with equal 
differences of angle corresponding to equal changes in the radian measure. In line 6 we use 
miaux_fit to normalize this radian measure to the range [0.0,1.0], and call this fractional value 
the altitude. 


We'll use the altitude as a lookup index into an array of discrete colors defined by a small set 
of key color values associated with positions along the ramp. For the variation between colors, 
we'll scale intermediate color channel values using the function miaux_sinusoid_fit. 


For example, if we have four color values, we’ll need to call miaux_sinusoid_fit with three 
different sets of arguments depending upon where in the range of altitude values our current 
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direction vector lies. 


Keys Values Function call for altitude value v 


O.0to 0.2 0.0t00.3 «miaux_sinusoid_fitty, 0.0, 0.2, 0.0, 0.3) 
0.2to0.7 O3to0.8 miaux_sinusoid_fit(v, 0.2, 0.7, 0.3, 0.8) 
0.7to1.0 O8to1.0 miaux_sinusoid_fit(v, 0.7, 1.0, 0.8, 1.0) 


Figure 21.4: Piecewise function definition 


Graphing these values, we can see the construction of the complete curve from the piecewise use 
of miaux_sinusoid fit. 
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Figure 21.5: Constructing a smooth curve from sinusoidal pieces 


Using this method for the red, green and blue channels of a set of colors, we can create a ramp of 
colors. 


red 
0.9 ' blue 
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0.4 green 


Figure 21.6: Channel curves from sinusoidal pieces 


As you can see from Figure 21.6, smaller differences in key positions for the sinusoid subsections 
will produce rapid changes of slope. We may not be as concerned with the smoothness of the 
curve as we are with the artistic requirement that we can produce certain color values at specific 
positions along the curve. 


Prog 403, 3.27. Initialization 
and Cleanup 


Prog 391, 3.26.17. Memory 
Allocation 
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21.3. Efficient shader access to a color ramp 


We could write a function that returns a color based on the definition of the key color ramp points 
and the current direction vector. But because miaux_sinusoid_fit is relatively time-consuming, 
it will be more efficient to create a lookup table to store pre-computed colors implemented as an 
array of floating point values. 


To provide for one-time creation of lookup tables and other actions that should not be done for 
every sample, a shader can optionally define functions that execute before and after the shader 
itself. These are called the shader’s init and exit functions. We’ll allocate memory and define 
values for a lookup table for colors in an init function, use that lookup table in the main shader, 
and then release the memory used by the lookup table in the exit shader. 


To implement the lookup table, we’ll create an array and pass it to a function in which we fill it 
with values calculated with piecewise use of miaux_sinusoid_fit: 


void miaux_piecewise sinusoid ( 
miScalar result[], int result count, 
int key count, miScalar key positions[], miScalar key values [] ) 


int key, i; 
for (key = 1; key < key count; key++) { 
int start = (int) (key_positions[key-1] * result_count) ; 
int end = (int) (key _positions[key] * result_count) - 1; 
for (i = start; i <= end; i++) { 
result [i] = miaux_sinusoid_ fit ( 
i, start, end, key values[key-1], key _values[key]) ; 


Figure 21.7: Function miaux_piecewise_sinusoid 


The key_values array argument in line 3 contains the series of explicit values between which 
intermediate values are calculated using miaux_sinusoid_fit in lines 10-11. The starting and 
ending positions expressed as values in the range [0.0,1.0] are converted into integer array indices in 
lines 7-8. The loop in lines 9-12 fills in the lookup table entries with miaux_sinusoid_fit. 


For any altitude value “between” the entries of our lookup table, we can do a simple interpolation 
between the nearest table entries. 


miScalar miaux_interpolated_lookup(miScalar lookup_table[], int table size, 
miScalar t) 
{ 


int lower_index = (int) (t * (table_size - 1)); 
miScalar lower value = lookup table[lower_ index] ; 


int upper_index = lower index + 1; 
miScalar upper value = lookup _table[upper_ index] ; 
return miaux_fit ( 
t * table size, lower_index, upper index, lower value, upper value) ; 


Figure 21.8: Function miaux_interpolated_lookup 
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Our first environment shader based on a lookup table is chrome_ramp. It uses the color ramp of 
Figure 21.6 to imitate the cliché of airbrushed chrome. 


declare shader 


color "chrome ramp" () 
end declare 


Figure 21.9: Shader declaration of chrome_ramp (p.557) 


We first need to define a struct with a predefined size for the lookup table in chrome_ramp. 


#define RAMPSIZE 1024 


typedef struct { 
int Yr size, g size, b_ size; 
miScalar r[RAMPSIZE] ; 
miScalar g[RAMPSIZE] ; 
miScalar b[RAMPSIZE] ; 

} channel _ramp_ table; 
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static channel ramp table *ramp; 


Figure 21.10: Source code of struct channel_ramp_table with static pointer variable ramp (p.557) 


We'll only have one lookup table for any use of the chrome shader throughout the rendering of 
a scene, so in line 10 we can define a static pointer to this structure. (In the next section we’ll see 
what we need to do when different shader calls may have different lookup tables.) 


The initialization function for a shader is named by appending “_init” to the name of the shader 
function. If mental ray finds that a function of that name has been defined, it runs the function 
before the main shader function. The init function for chrome ramp is chrome_ramp_init. 


miBoolean chrome_ramp_init ( 
miState *state, void *params, miBoolean *instance init required) 


int key count = 4; 


miScalar key positions[] = {0, .49, }; 
miScalar red[] 10.95, 06.66, 0. }; 
} 
} 


/ 


miScalar green[] {0.85, 0.6, 
miScalar blue[] = {0.75, 0.48, 


/ 


ramp = (channel ramp _table*)mi_mem_allocate(sizeof (channel ramp_table)); 


miaux piecewise sinusoid(ramp->r, RAMPSIZE, key count, key positions, red) ; 
miaux_ piecewise sinusoid(ramp->g, RAMPSIZE, key count, key positions, green) ; 
miaux piecewise sinusoid(ramp->b, RAMPSIZE, key count, key positions, blue) ; 


return miTRUE; 


Figure 21.11: Source code of init shader of chrome_ramp (p.557) 


In line 11, we allocate memory for our lookup table, assigning to the static pointer variable ramp. 


Allocation of memory in shaders should use the library function mi_mem_allocate. In lines 13- Prog 391, 3.26.17. Memory 
Allocation 
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15 we fill the r, g, and b fields with the piecewise sinusoid ramps. Because we are defining data 
that is constant for all uses of the shader, we can ignore the third argument to the init function 
(though it will become necessary in the next section). 


Once the init function has created the lookup table, the chrome_ramp shader function uses those 
lookup table values based on the altitude. 


miBoolean chrome_ramp ( 
miColor *result, miState *state, void *params ) 


miScalar altitude = miaux_altitude(state) ; 
result->r = miaux_interpolated_lookup(ramp->r, RAMPSIZE, altitude) ; 
result->g miaux interpolated _lookup(ramp->g, RAMPSIZE, altitude) ; 


result->b = miaux_interpolated_lookup(ramp->b, RAMPSIZE, altitude) ; 
return miTRUE; 


Figure 21.12: Source code of shader chrome_ramp (p.557) 


Most of the work is done in chrome_ramp_init, so the main shader chrome_ramp simply calculates 


the interpolated value from the lookup table in lines 5-7 based on the altitude value from line 
line 4. 


If an exit function has been defined, it will be called when rendering is complete. 


miBoolean chrome_ramp_exit(miState *state, void *params) 


{ 


mi_mem_release (ramp) ; 
return miTRUE; 


Figure 21.13: Source code of exit shader of chrome_ramp (p.557) 


The exit function is responsible for deallocating any memory allocated in the init function and 
any other cleanup tasks that may be required. The function mi_mem_release is used to deallocate 
any memory allocated with mi_mem_allocate. Notice that variable ramp is not defined anywhere 
in the function—it is a static variable with global scope in the shader source file. 


By attaching the chrome_ramp shader to the camera, the direction of the eye rays determines the 
color acquired from the chrome lookup table. 
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camera "cam" 
output "rgba" "tif" "environment 2.tif" 
focal 1.5 


aperture 1.5 
aspect 1 
resolution 300 300 
environment 


"chrome_ramp" () 
end camera 


material "corinthian_material" 
"lambert" ( 
"diffuse" .95 .65 .75, 
‘lightse™: (|"light-inet"]. }) 
end material 


Figure 21.14: Shader chrome_ramp attached to the camera as an environment shader. 


If we use a material shader that sends rays into areas of the scene without objects, the camera’s 

environment shader will also be used for that material. The specular_reflection shader in 

Figure 14.3 calls mi_trace_environment when mi_trace_reflection returns miFALSE. This will Prog323, 3.26.2. RC 
occur when a ray leaves the scene or the trace depth has been exceeded. a 


camera "cam" 
output "rgba" "tif" "environment 3.tif" 
focal 1.5 
aperture 1.5 
aspect 1 
resolution 300 300 
environment 
"chrome ramp" () 
end camera 


material "corinthian_material" 
"specular reflection" () 
end material 


Figure 21.15: Shader chrome_ramp used for rays reflected with shader specular_reflection. 


21.4 Using parameter arrays for color channels in the ramp 


The chrome_ramp shader fixed the color values used for the lookup table ramp. In shader 
channel_ramp, the key positions and the channel values are defined by arrays of scalar 
parameters. 


Prog 407, 3.28.2. Shader 
Instance Data 
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declare shader 
color "channel ramp" ( 
array scalar "keys", 


atray scalar ."r",; 

array scalar "g", 

array scalar "b" ) 
end declare 


Figure 21.16: Shader declaration of channel_ramp (p.558) 


21.4.1 Allocating memory in the init function 


During rendering, the channel_ramp shader will refer to a lookup table to calculate its color 
values. But unlike the chrome_ramp shader, we can’t use a statically declared variable for the 
table—different ramp arguments when the shader is used in the scene will require different 
lookup tables. Each use of a shader in the scene is called a shader instance, and we may need to 
have a separate lookup table for each of them. 


The arguments for the init function define how the shader is called and used. In the following 
table, the argument names are those used in the init functions in this chapter. 


Type Name Description 
miState* state State when main function 1s called 
varying params Main shader parameter structure 


miBoolean* instance_init_required Signal to run init function for shader instances 


Figure 21.17: Init function arguments 


The init function for a shader can be called multiple times. It is first called a single time without 
shader parameters, signified by a NULL pointer as its second argument value. This single call 
allows for any initialization that is required for every use of the shader in the scene. 


If the third argument, a miBoolean pointer, is set to miTRUE in this call, mental ray will call the 
init function for each shader instance, created each time the shader is used in the scene. In each of 
these shader instance calls, the second argument pointer is set to a parameter structure containing 
the field values defined in the scene. 


A typical structure for init functions examines the parameter argument and sets the instance init 
signal in the following way: 
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miBoolean shader init ( 
miState *state, struct shader *params, 
miBoolean *instance init required) 


if (params == NULL) { 
/* Do main shader initialization */ 
*instance init required = miTRUE; 
} else { 
/* Do instance-based shader initialization */ 
} 


return miTRUE; 


Figure 21.18: Template for init shader function 


Since we may have multiple lookup tables due to multiple shader instances, we need to allocate 
memory separately for each shader instance using a mechanism called the shader user pointer. 
Once we have acquired this pointer using the MIQ_FUNC_USERPTR query code with mi_query, we 
can safely allocate and deallocate memory for it using mi_mem_allocate and mi_mem_release as 
we did before in chrome_ramp. 


Acquiring the user pointer will always require a similar sequence of function calls, including a 
syntactically tricky use of mi_query, so we’ll put the required statements in a utility function, 
miaux_user_memory_pointer. 


void* miaux user memory pointer(miState *state, int allocation_size) 


{ 


void **uper pointer; 
mi_query(miQ FUNC_USERPTR, state, 0, &user_ pointer) ; 


*user pointer = mi_mem_allocate(allocation_size) ; 


} 


return *user, pointer; 
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Figure 21.19: Function miaux_user_memory_pointer 


The mi_query call in line 4 provides a pointer to a region of memory which we can access for use 
in our shader. However, that call does not allocate any memory—we need to do that separately, 
as on line 6. Notice that the allocation is only performed if the allocation_size argument 1s 
not zero. With a value of zero, we can acquire the same pointer to memory when we need access 
to it during the main shader call. 


Most of the code for the init function for channel_ramp acquires parameter values and checks 
for inconsistencies. 


Prog 378, 3.26.12. Auxiliary 
Functions 


348 21. The environment of the scene 


miBoolean channel _ramp_init ( 


{ 


miState *state, struct channel ramp *params, miBoolean *instance_init required) 


if (params == NULL) { /* Main shader init (not an instance) */ 
*instance init required = miTRUE; 
} else { /* Instance initialization */ 
mt nm Keys, n_r,; ng, 1d; 
miScalar *keys, *red, *green, *blue; 
channel ramp_table *ramp; 


n keys = *mi_eval_ integer (&params->n_keys) ; 
keys = mi_eval_scalar(params->keys) + 
*mi eval integer (&params->i keys) ; 


if ((n_r = *mi_eval_integer(&params->n_r)) != n_keys) 
mi _fatal("Incorrect number of red values: %d", nr); 
red = mi_eval_scalar(params->r) + *mi_eval_ integer (&params->i 1) ; 


if ((n_g = *mi_eval_integer(&params->n_g)) != n_keys) 
mi_fatal("Incorrect number of green values: %d", ng); 
green = mi_eval_scalar(params->g) + *mi_eval_integer(&params->1i_g) ; 


if ((n_b = *mi_eval_integer(&params->n_b)) != n_keys) 

mi _fatal("Incorrect number of blue values: %d", n_b); 
blue = mi_eval_scalar(params->b) + *mi_eval_ integer (&params->1i_b) ; 
ramp = miaux_user_ memory pointer(state, sizeof(channel ramp_table) ) ; 
miaux_ piecewise sinusoid(ramp->r, RAMPSIZE, n_keys, keys, red) ; 
miaux piecewise sinusoid(ramp->g, RAMPSIZE, n_keys, keys, green) ; 


miaux_ piecewise sinusoid(ramp->b, RAMPSIZE, n_keys, keys, blue); 


return miTRUE; 


Figure 21.20: Source code of init shader of channel_ramp (p.558) 


Since the key and color channel arrays can have differing numbers of elements, we should handle 
this condition in some way in our shader. We’re building the color ramps in the init shader, so 
it will have the responsibility to check for parameter consistency. The simplest thing we can do 
is simply require that all the arrays are the same length. After evaluating the scalar array of keys 
in lines 11-13, we compare the number of key elements with the number of red values (lines 15- 
17), green (lines 19-21) and blue (lines 23-25), and call mi_fatal to stop rendering entirely if any 
inconsistencies are found. Other policies are possible; we could repeat array elements if there 
aren’t enough and remove array elements from the end if there are too many. 


Utility function miaux_user_memory_pointer creates the channel_ramp_table struct in line 27. 
The number of bytes to be specified for the functions allocation_size argument is determined 
by the C operator sizeof in line 27. We then separately fill in the r, g, and b fields 
of channel_ramp_table in lines 29-31 with miaux_piecewise_sinusoid just as we did in 
chrome_ramp. 


Now that the ramp data has been calculated in the init function, the main shader simply acquires 
the user pointer and does an interpolated lookup. 
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miBoolean channel ramp ( 
miColor *result, miState *state, struct channel ramp *params ) 


miScalar altitude = miaux_altitude(state) ; 
channel ramp_table *ramp = miaux_user_memory_pointer(state, 0); 


result->r miaux_interpolated_ lookup(ramp->r, RAMPSIZE, altitude) ; 
result->g miaux_ interpolated _lookup(ramp->g, RAMPSIZE, altitude) ; 
result->sb miaux_ interpolated _lookup(ramp->b, RAMPSIZE, altitude) ; 


uf 
a 
3 
4 
> 
6 
7 
8 


HH 
How 


return miTRUE; 


= 
NO 


Figure 21.21: Source code of shader channel_ramp (p.558) 


Notice that miaux_user_memory_pointer is used in line 5 to access the user pointer without 
also allocating memory by passing an allocation_size of zero. Once we have this 
pointer, the result channel values simply require three lookup operations, just as we did in 
chrome_ramp. 


21.4.2 Releasing the memory allocated through the user pointer 


As we saw in chrome_ramp, the deallocation of memory and any other cleanup actions should 
take place in the exit shader function, named by appending “_exit” to the main shader’s name. 
But unlike chrome_ramp, we need to release the memory we allocated in the init function through 
a user pointer. Since this is a typical requirement of the exit function, we'll put the user pointer 
access and deallocation into another utility function, miaux_release_user_memory. 


miBoolean miaux release user memory(char* shader name, miState *state, void *params) 
{ 
if (params != NULL) { /* Shader instance exit */ 
void **user pointer; 
if (!mi_query(miQ FUNC_USERPTR, state, 0, &user_pointer) ) 
mi _fatal("Could not get user pointer in shader exit function %s_ exit", 
shader name) ; 
mi_mem_ release (*user_pointer) ; 


} 


return miTRUE; 


Figure 21.22: Function miaux_release_user_memory 


Like the init function, the parameter pointer in the second argument of the exit function is NULL 
for its first call. We only allocated memory for shader instances, so we only callmi_mem_releases 
in line 8 if the parameter pointer has a value in the conditional test in line 3, that is, if this is an 
exit function called because a shader instance has finished execution. 


In case there is an error in acquiring the user pointer, we’ll print out an error message and stop 
rendering through a call to mi_fatal in lines 6-7. Though it is not strictly necessary, passing 
in the name of the shader as argument shader_name allows us to display a more helpful error 
message with mi_fatal. 


Our exit function for channel_ramp is now just a call to miaux_release_user_memory. 
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1 miBoolean channel ramp _exit(miState *state, void *params) 
2 { 
3 
4 


return miaux_ release user _memory("channel ramp", state, params) ; 


} 


Figure 21.23: Source code of exit shader of channel_ramp (p.558) 


21.4.3 Using channel_ramp in a named shader 


We’ll define a named shader, called sunset, using shader channel_ramp in a scene. 


shader "sunset" 
"channel ramp" 


camera "cam" 
output "rgba" "tit" “environment 4.tif" 
focal 1.5 
aperture 1.5 
aspect 1 
resolution 300 300 
environment 
= "sunsec”" 
end camera 


material "corinthian material" 
"specular reflection" () 
end material 


Figure 21.24: Color ramp values defined with arrays for key positions and channel values 


With more key positions in the channel_ramp shader instance than in the chrome_ramp instance 
in the previous scene, we can create a greater variety of colors in the ramp. 
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Figure 21.25: Color curves specified in the scene file for shader channel_ramp 
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21.5 Acolor array as a shader parameter 


Much of the code in the main channel_ramp function involved the acquisition of the separate 
parameter arrays for the key positions and the channel values. We also needed to check that the 
same number of values were passed for all the arrays. In the next shader, color_ramp, we'll use 
an array of colors for the definition of the ramp. 


declare: shader 
color "color ramp" { 


array color "colors" ) 
end declare 


Figure 21.26: Shader declaration of color_ramp (p.560) 


Since we are free to interpret the channels of colors in any way we choose, we'll use the alpha 
channel for our position values. 


void miaux_piecewise color sinusoid ( 
miColor result[], int result count, int key count, miColor key values [] ) 


int key, i; 
for (key = 1; key < key count; key++) { 
int start = (int) (key values [key-1].a * result_count) ; 
int end = (int) (key_values [key] .a * result_count) - 1; 
for (i = start; i <= end; i++) { 
result [i].r = 
miaux_Sinusoid fit ( 


HR 
FPOWUDIAHDUOAWNE 


i, start, end, key _values[key-1].r, key values [key] .r); 
result [i] .g = 
miaux_ sinusoid fit ( 
i, start, end, key values[key-1].g, key_values[key] .g) ; 
result [i] .b = 
miaux sSinusoid fit ( 
i, start, end, key values[key-1].b, key_values [key] .b) ; 


Figure 21.27: Function miaux_piecewise_color_sinusoid 


In line 2 we pass a pointer to an array of miColor values that has already been allocated in the 
calling function. Lines 6 and 7 use the floating point values of the alpha channel in the range 
[0.0,1.0] to define the position of the key color values. Lines 9-17 fill in the channels of the color 
array using miaux_sinusoid_fit as we did before with miaux_piecewise_sinusoid. 


The interpolation function is the direct extension to array elements of type miColor from the 
function that calculated floating point values, miaux_interpolated_lookup. 
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1 void miaux_interpolated color lookup(miColor* result, 

2 miColor lookup table[], int table size, 
3 miScalar t) 

4% 

5 int lower_index = (int) (t * table size) ; 

6 miColor lower value = lookup table[lower_ index] ; 

ar int upper _index = lower index + 1; 

8 miColor upper value = lookup table[upper_ index] ; 

] result->r = miaux fit(t * table size, lower_index, upper _index, 
10 lower value.r, upper value.r) ; 
11 result->g = miaux_fit(t * table size, lower_index, upper_index, 
LZ lower value.g, upper value.g) ; 
13 result->b = miaux_fit(t * table size, lower_index, upper_index, 
14 lower value.b, upper value.b)j; 
15 } 


Figure 21.28: Function miaux_interpolated_color_lookup 


Lines 5-8 are identical to miaux_interpolated_lookup, but in lines 9-14 we call miaux_fit three 
times for the red, green, and blue channels of the two color entries in the lookup table. 


Now that we have a single function for generating a lookup table of type miColor, the init 
function for shader color_ramp is much simpler than for channel_ramp. 


miBoolean color _ramp_ init ( 
miState *state, struct color ramp *params, 
miBoolean *instance init required) 


if (params == NULL) { /* Main shader init (not an instance) */ 
*instance init required = miTRUE; 
} else { /* Instance initialization */ 
int n_colors = *mi_eval_ integer (&params->n_colors) ; 
miColor *colors = 
mi _eval_color(params->colors) + *mi_eval_integer(&params->1i colors) ; 
miColor *ramp = 
miaux_ user memory pointer(state, sizeof(miColor) * RAMPSIZE) ; 
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miaux piecewise color sinusoid(ramp, RAMPSIZE, n_colors, colors) ; 


} 


return miTRUE; 
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Figure 21.29: Source code of init shader of color_ramp (p.560) 


The color array is accessed in lines 8-10. The shader user pointer memory allocation is handled 
by the call to miaux_user_memory_pointer in lines 11-12, resulting in an array of type miColor. 
The lookup table is filled by the call in line 18 to miaux_piecewise_color_sinusoid. 


The main shader function is also simpler than channel_ramp due to the use of an array of miColor 
values. 
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miBoolean color_ramp ( 
miColor *result, miState *state, struct color ramp *params ) 


i 

2 

3 { 

+ miColor *ramp = miaux_user_ memory pointer(state, 0); 
5 miaux interpolated color lookup ( 

6 result, ramp, RAMPSIZE, miaux_altitude(state) ) ; 
7 return miTRUE; 

8 


} 


Figure 21.30: Source code of shader color_ramp (p.560) 


The array of miColor values, ramp, is acquired in the same manner as in the init function. Since 
the result of function miaux_altitude is only used once, it is called directly as an argument in 
line 6. 


Like channel_ramp, the shader exit function for color_ramp uses miaux_release_user_memory. 
1 miBoolean color _ramp_exit(miState *state, void *params) 
2 { 
3 
4 


return miaux_release user memory("color_ ramp", state, params) ; 


Figure 21.31: Source code of exit shader of color_ramp (p.560) 


The colors and their ramp position values (as specified by the alpha channel) are defined in the 
scene file with the array syntax for parameters: a comma between each set of four color channel 
values, surrounded by square brackets. 


shader "sunset" 
"OOLGE Famp™ 

"oolorse" 

ise 

a 


camera "cam" 
output "rgqba" "tif" "environment 5.tif" 
tecal: 1.5 
aperture 1.5 
aspect 1 
resolution 300 300 
environment 
= "sunset" 
end camera 


material "corinthian_ material" 
"specular reflection" () 
end material 


Figure 21.32: Color ramp values defined by an array of colors with alpha as the key value 


Larger blue values in the middle of the ramp give it a more desaturated look than in the previous 


shader. 


354 21 The environment of the scene 


red 03 
green 0.2 blue 
blue o. “ 


Figure 21.33: Color curves specified in the scene file for shader color_ramp 


21.6 Environment shaders for cameras and objects 


Different environment shaders can be used for the camera and object instances. For any object 
instance without an environment shader, the camera’s environment shader will be used as the 


default. 


shader "red sunset" 
"color ramp" ( 
‘eolors” { 


shader "pink sunset" 
"color ramp". { 
toolors' 16 


0 
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camera "cam" 
output "rqba”" "tif" “environment 6.tif" 
rocal<1a.5 
apercure 1.5 
aspect 1 
resolution 300 300 
environment 
= “red sunset" 
end camera 


material "corinthian_ material" 
"specular reflection” {) 
environment = "pink sunset" 
end material 


Figure 21.34: Different environment shaders used for the camera and object 
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21.7. Encapsulating constant data in a Phenomenon 


A shader with a complex set of parameter values that will be used repeatedly is an ideal candidate 
for a Phenomenon. In the simplest case, the shader is simply wrapped by the Phenomenon and 
is named as the root. 


declare phenomenon 
color "red sunset" () 


shader "sunset" 
"color ramp" 
"solora” 

ee 


shader "sunset" 
"“Solor. ramp" 
‘eolorsa®™ 

[ 0.3 


root = “sunset” 


end declare 


Figure 21.35: Encapsulating a named shader in a Phenomenon 


Phenomena based on color_ramp can be defined as a separate resource accessed by scene files in 
the same manner as shader declarations. 


declare phenomenon 
color "red sunset" () 
shader "sunset" 
"color _ramp" ( 
‘eoLors” 
e '. 
Oi. 


) 
YOoocG = 
end declare 


"Sunset" 


declare phenomenon 
color "pink sunset" 


shader "sunset" 
"color_ramp" 
"colors" 

[ 6.3 

0. 


) 
roct. = 
end declare 


"Sunset" 


Figure 21.36: Encapsulating a particular set of color_ramp parameters as Phenomena 


Prog 70, 2.5. Phenomena 


356 21. The environment of the scene 


Phenomena red_sunset and pink_sunset encapsulate color_ramp and can now take the place 
of anonymous shaders in their use for the environment shaders in the camera and in the instance 
of the material. 


camera "cam" 
output "rgba" "tif" “environment 7.tif" 
tocal 1.5 
aperture 1.5 
aspect 1 
resolution 300 300 
environment 
"Dink sunset" () 
end camera 


material "corinthian material" 
"specular reflection" () 
environment 


"red sunset" () 
end material 


Figure 21.37: Defining Phenomena to encapsulate complex shader parameter settings 


There is little syntactic difference between the shaders and Phenomena in Figures 21.34 and 21.37. 
We can think of the Phenomenon in this case of a single-shader network as a container for the 
shader and its parameter values. However, because the syntax of a Phenomenon when it is used is 
identical to that of an anonymous shader, a Phenomenon can be added to the graphical interface 
of an application in the same manner as a shader. This allows sets of custom Phenomena to 
be easily developed on a per-project basis, capturing art-directorial decisions by encapsulating 
particular shader parameters in a well-named Phenomenon. 


Chapter 22 


A visible atmosphere 


In previous chapters, we have attached shaders to the instances of geometric objects and to the 
camera. As a ray proceeds from our eye (the camera), we intersect geometric surfaces. Shaders 
associated with that surface can specify its color and the modification of its geometric properties. 
However, for natural phenomena like fog and smoke, no similar geometric surfaces exist. Or 
at least, no geometric surfaces that we could effectively model exist—we hardly want to create 
individual geometric objects for the enormous number of microscopic water particles that a cloud 
contains. 


Traditional solutions to this problem have included rendering a smaller number of larger objects, 
each using a texture map of transparency containing cloud-like patterns. By attaching a volume 
shader to the camera, we have a chance to modify the color resulting from a ray’s progression 
through the space. By examining the distance of objects from the camera, we can change the 
resulting color in a manner similar to the attenuation of the background by fog. We'll also 
estimate more complex fog structures by calculating the thickness of the fog multiple times along 
the eye ray as it travels through the scene. 


22.1 Volume shaders and the camera 


The camera definition specifies the geometry of the projection of the image to be rendered, but 
by default does not modify the color values returned by the rays as they sample the scene. 
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camera "cam" 
output "rgba" "tit" 
"atmosphere 1.tif" 
Focal 1.5 
aperture 1 
aspect l 
resolution 300 300 
end camera 


Figure 22.1: A scene with a typical camera 


Prog 250, 3.10. Volume 
Shaders 
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We'll define a volume shader that simulates fog by linearly blending the background color with 
a color parameter of the shader. At the full fade distance, the resulting color of the shader will be 
the fog color. For the position of any object nearer to the camera than the full fade distance, the 
resulting color will be the result of blending the two colors based on distance. 


declare shader 
color "feg" { 


scalar "full fade distance" default 10, 
color "fog color" default 111 ) 
end declare 


Figure 22.2: Shader declaration of fog (p.561) 


Prog 111, 2.7.2.3. Other A volume shader is attached to the camera with the volume statement followed by a shader 
Camera Statements call 


camera "cam" 
output "rgba" "tif" 
“atmosphere 2.tif" 
fowal. 1.5 
aperture 1 
aspect 1 


resolution 300 300 


volume 
"Fog W ( 
"full fade distance" 5, 
"log Soler’ .37 .37 1) 


end camera 


Figure 22.3: Camera with fog volume shader, full fade distance set to 5 


Prog 207, 3.4.3. Rays In a camera’s volume shader, the camera’s position is state->org, the direction of the eye ray 
is state->dir, and the distance from the camera to the point being sampled is state->dist. 
Prog 210, 3.4.4. Intersection 


state->org vv state->dir 


state->dist 


Figure 22.4: Fields in miState useful in a volume shader 


When a volume shader is called, the result contains the value background color calculated by 
the material shader of the eye ray, and it is this color that the volume shader will modify. Though 
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the shader is part of the camera definition, the syntax of the shader call is the same as for those 
shaders contained in a material. We can use this background color and the value of state->dist 
to create an apparent change of color based on distance, shader fog. 


struct fog { 
miScalar full fade distance; 
miColor fog color; 


hi 


miBoolean fog ( 


{ 


miColor *result, miState *state, struct fog *params ) 
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miScalar full fade distance = *mi_eval_scalar(&params->full fade distance) ; 
miColor *fog color = mi_eval_color(&params->fog color) ; 
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if (state->dist > full fade distance || state->dist == 0.0) 
*result = *fog dolor; 
else 
miaux_blend_colors ( 
result, fog color, result, state->dist/full fade distance) ; 
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return miTRUE; 
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Figure 22.5: Shader source of fog (p.561) 


In a volume shader attached to the camera like fog, the value of state->dist is the distance Prog 210, 3.4.4. Intersection 
from the camera to the object that produced the color stored in the result argument. If the eye 

ray did not strike any objects, then state->dist will be zero. If state->dist is greater than 

the full_fade_distance parameter, then by definition the object is fully occluded by the fog. 

If state->dist is zero, we'll also set the volume’s result to the fog color, assuming that the full 

fog color would build up over the span of an infinitely long ray. These conditions for the full fog 

value are tested in line 12, and the result value is set to the fog color in line 13 if they are met. If 

not, then we blend the background color with the fog color based on the fractional distance from 

the camera to the background object in lines 15-16. 


camera "cam" 
ouepat "reba" "tit" 
"atmosphere 3.tif" 
focal 1.5 
aperture i 
aspect 1 
resolution 300 300 
volume 
W fog W ( 
"full fade distance" 3.1, 
“fog ecoler" 1 1 .9 } 


end camera 


Figure 22.6: Camera with fog volume shader, full fade distance set to 3.1 


Rend 171, 6.3. Ray Marching 
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22.2 Changing the fog density 


A modification of the background color based simply on distance simulates fog that is evenly 
distributed in the space, obscuring the objects within it. But if the fog varies in its thickness 
throughout the space, then a simple blending of the background and fog colors won’t be sufficient 
to represent that variation. 


For example, imagine a layer of fog close to the ground. Over some vertical distance this 
fog diminishes so that it no longer has any visual effect. Looking through this fog, we could 
define three possible layers in which the fog is fully opaque, partially transparent, and non- 
existent. 
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Figure 22.7: Defining different fog density based on height 


The thickness of our simulated fog now varies along the course of the eye ray. However, if we 
can calculate how thick the fog is at any point in the space, then we can accumulate a series 
of thickness measurements along a ray to arrive at an approximation of the fog’s opacity when 
looking along that ray. Because we are incrementally proceeding along the ray in even steps, this 
technique is often called “ray marching.” 
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Figure 22.8: Points along the ray for fog density accumulation 


In Figure 22.8, you can see that the result of adding the measurements at the points along ray A 
will result in a larger value than in ray B. Since ray C never leaves the region in which there isn’t any 
fog, the total fog measurement for that ray will be 0.0, and the shader will return the unmodified 
value of the material color sampled by ray C before the volume shader was called. 


For volume effects, we’ll assume that we can determine the density for a given point in the space, 
in which a density of 0.0 is transparent, and a density of 1.0 is fully opaque. For fog, we’ll think 
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of density as the degree to which the fog obscures the objects within it. In general, we’ll assume 
that there is a functional relationship between positions in space and density. 


D = faensity(X,; Z) 


For the series of march points, we are actually defining the density along a segment of the ray that 
is bounded by adjacent march points. To take this into account, we’ll call this segment the march 
increment, and multiply this value times the point’s value of density, making the simplifying 
assumption that the density is constant within this segment. This assumes that the density values 
define density per some length in the volume, so we’ll also multiply the march increment density 
by the unit density value, the length in the space that would have a density value of 1.0. Fora 
march increment length of L and a unit density of Dyniz, we will therefore define our incremental 
density as: 


LD pepenveni —_ } density (%5 y; gy 8 ier 


Our assumption is that one of the endpoints of the march increment is a good approximation for 
the density along the entire segment. The smaller our march increment, then, the more accurately 
we will approximate the value of the density along the entire ray. For simplicity in our examples 
in this chapter and the next, we'll also make the non-physical assumption of a linear relationship 
between density and transparency, rather than an exponential one. 


The shader we’ll write that implements ray marching for volume effects defined by the camera is 
called ground_fog. 


declare shader 
color "ground Tog" { 
color "Tog color" default 
color "fog density" default 


scalar "fade start" default 

scalar "fade end" default 

scalar "unit density" default 

scalar -"“march_increment" default 
end declare 


Figure 22.9: Shader declaration of ground_fog (p.562) 


Rendering the scene from Figure 22.1 with fade_start and fade_end values chosen to obscure 
the ground plane but allow the lower part of the columns to be visible produces the image in 
Figure 22.10. 
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camera "cam" 
Sutput “reba” "ELE" 
"atmosphere 4.tif" 
focal 1.5 


aperture 1 
aspect 1 
resolution 300 300 
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volume 
"ground fog" ( 
“Eog olor" ).55 1.3, 
"fade start" -.8, 
"face end" =-.1, 
"march increment" 


Sx RX. 


end camera 


Figure 22.10: The effect of ray marching in a volume shader to simulate fog of non-uniform density 


To define ray marching points, we need an initial point, a direction, and a distance. If the direction 
vector is normalized its length is 1.0, so we can multiply the direction vector by the length and 


add this vector to the starting point. The utility function miaux_point_along_ vector determines 
points in this way. 


void miaux_point_along_ vector ( 
miVector *result, miVector *point, miVector *direction, miScalar distance) 


result->x = point->x + distance * direction->x; 
result->y point->y + distance * direction->y; 
result->z = point->z + distance * direction->Z; 


Figure 22.11: Function miaux_point_along_vector 


In a volume shader, we will typically use the state variables described above, state->org and 
state->dir, for the starting point and direction for ray marching. 


void miaux_march_point ( 
miVector *result, miState *state, miScalar distance) 


miaux_ point along vector(result, &state->org, &state->dir, distance) ; 


Figure 22.12: Function miaux_march_point 


In the ground_fog shader, our description of the levels of the fog is in world space coordinates, 
so we need to transform the march point into that space, too. 
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void miaux_world_space_march_point ( 


{ 


miVector *result, miState *state, miScalar distance) 


1 

2 

3 

4 miaux_ march point(result, state, distance) ; 
5 mi.vector_to world(state, result, result); 
6 } 


Figure 22.13: Function miaux_world_space_march_point 


The structure of ground_fog is dominated by the ray marching loop as the fog density is evaluated 
along the length of the ray based on the points determined by miaux_point_along_ray. 


struct ground fog { 
miColor fog color; 
miColor fog density; 
miScalar fade start; 
miScalar fade end; 
miScalar unit density; 
miScalar march_increment; 


A®ANAHAUHFWN FE 


hg 


miBoolean ground fog ( 
miColor *result, miState *state, struct ground fog *params ) 
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miScalar fade start, fade_end, fog density, distance, density factor, 
march increment, unit density, accumulated density; 
miVector march point; 
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if (state-sdist == 0) 
return miTRUE; 
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fade start = *mi_eval_scalar(&params->fade_ start) ; 

fade _end = *mi_eval_ scalar (&params->fade_end) ; 

fog density = *mi_eval_scalar(&params->fog density) ; 

march increment = *mi_eval_ scalar (&params->march_increment) ; 
unit _density = *mi_eval_scalar(&params->unit density) ; 
accumulated density = 0.0; 
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for (distance = 0; distance < state->dist; distance += march_increment) { 
miaux_world space march point (&march_ point, state, distance) ; 
density factor = miaux_fit clamp ( 
march point.y, fade_start, fade _end, fog density, 0.0); 
accumulated density += density factor * march_increment * unit density; 
if (accumulated density > 1.0) { 
*result = *mi_eval_color(&params->fog_ color) ; 
return miTRUE; 
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} 
if (accumulated density > 0.0) 


miaux_blend_colors(result, result, mi_eval_color(&params->fog_ color), 
1.0 - accumulated density) ; 
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return miTRUE; 
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Figure 22.14: Shader source of ground_fog (p.562) 


Unlike our simple fog shader that only looked at the length of the ray, we can’t make a 
determination of fog density just by looking at the length of the ray. If the ray doesn’t strike any 
objects so that the distance is zero in line 17, then we simply exit the shader in line 18. 
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Now that we know that the eye ray has struck an object in the scene, the for block in lines 27-36 
implements the ray march. A series of points along the eye ray are determined by accumulating 
the march_increment length into the distance variable in the for loop. This distance is provided 
as an argument to miaux_world_space_march_point in line 28 to find the current march point. 
The degree of fog density, the density_factor in line 29, is calculated using miaux_fit_clamp 
based on the fade_start and fade_end values in lines 29-30. The maximum density of the fog is 
specified by the shader parameter fog_density, used in the call to miaux_fit_clamp for values 
below fade_start. 


Shader parameter unit_density specifies the density of the fog through a single unit of 
measurement in the world space coordinate system. That absolute measure is multiplied by 
the march_increment parameter to scale the density_factor value (calculated in lines 29-30) to 
define the incremental density at that point in the ray march. This allows larger march_increment 
values (which require fewer march points to traverse the eye ray and are therefore faster to 
calculate) to serve as a usefully approximate test before more accurate and time-consuming 
results are obtained with smaller march_increments. 


In line 32, if the density accumulated so far along the ray march exceeds 1.0, then the ray has passed 
through a fully opaque region, and the ray march loop can stop, with the shader immediately 
returning the fog_color. If execution reaches line 37, however, the accumulated_density is less 
than 1.0. If it is greater than zero, then the background color defined in the result argument is 
blended with the fog_color based on the accumulated_density. If the accumulated_density 
is zero, then no fog-based modification of the color is required and the result value that contains 
the background color is the appropriate value for the volume shader to produce. 


22.3. Adding a debugging mode to a shader 


The possible parameters for ground_fog implied by Figure 22.7 included the height of the two 
boundary layers for fog density, fade_start and fade_end. But in a complex scene how can we 
be sure that we’ve set those height values correctly? To address this problem, we’ll write a shader 
called ground_fog_layers that adds a “visualization” technique to shader ground_fog. 


declare shader 
color "ground fog layers" ( 
color "tog color default 
color "fog density" default 
scalar "fade_start" default 
scalar "fade end" default 
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scalar "unit density" default 

scalar "march_increment" default 

boolean "show layers" default 

color "full fog_marker" default 

color "partial fog marker" default . 
end declare 
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Figure 22.15: Shader declaration of ground_fog_layers (p.563) 


Rendering the scene in Figure 22.10 with ground_fog_layers with show_layers set to on shows 
the depth off the partial and full fog layers. By default, the partial layer is tinted green, the full 
fog layer is tinted red. 
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{pt Pt pt pt P< 
a HS camera "cam" 
SHtput "raba" =“2e*" 
"atmosphere 5.t2i" 
focal 1.5 


aperture 1 
aspect 1 
resolution 300 300 


volume 
"ground fog layers" 
"show layers" on, 
“tog color™ .95 1 .3, 
“fae Start” \=.8, 
(Wee en": =, T1, 
"march increment" 


® 
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end camera 
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Figure 22.16: Using the show_regions parameter of ground_fog_layers to display the fog layers 


If parameter show_layers is set to on, then the shader’s ray marching behavior is replaced by 
a color scheme that displays the full and partial regions of fog density. In a volume shader, 
state->point is the surface that was struck by the ray. We can define a modification of the 
background color stored in result based on the y component of state->point. 
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struct ground fog layers { 
miColor fog _ color; 
miColor fog density; 
miScalar fade_start; 
miScalar fade_end; 
miScalar unit density; 
miScalar march_increment ; 
miBoolean show _layers; 
miColor full fog marker; 
miColor partial fog _ marker; 


hi 


miBoolean ground fog layers ( 
miColor *result, miState *state, struct ground fog layers *params ) 
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miScalar fade_start = *mi_eval_scalar(&params->fade_start) ; 
miScalar fade_end = *mi_eval_scalar(&params->fade_end) ; 
miVector world point, march point; 
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if (state->dist == 0.0) 
return miTRUE; 
else if (*mi_eval_boolean(&params->show_layers)) { 
miColor* full fog marker = 
mi eval color (&params->full fog marker) ; 
miColor* partial fog _ marker = 
mi eval color (&params->partial_fog_marker) ; 
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mi point to world(state, &world point, &state->point) ; 
if (world _point.y < fade_start) 
miaux multiply colors(result, result, full _fog_marker) ; 
else if (world_point.y < fade_end) 
miaux multiply colors(result, result, partial _fog_marker) ; 
} else { 
miScalar fog density = *mi_eval_scalar(&params->fog density) ; 
miScalar march_increment = *mi_eval_scalar(&params->march_increment) ; 
miScalar unit density = *mi_eval_scalar(&params->unit_density) ; 
miScalar accumulated density = 0.0, distance, density factor; 
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for (distance = 0; distance < state->dist; distance += march _increment) { 
miaux world space march point (&march point, state, distance) ; 
density factor = miaux_fit_clamp ( 
march point.y, fade start, fade _end, fog density, 0.0); 
accumulated density += 
density factor * march_increment * unit density; 
if (accumulated density > 1.0) { 
*result = *mi_eval_ color (&params->fog_ color) ; 
return miTRUE; 
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} 
} 
if (accumulated density > 0.0) { 


miaux blend _colors(result, result, mi_eval_color(&params->fog_color), 
1.0 - accumulated density) ; 
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} 
} 


return miTRUE; 
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Figure 22.17: Shader source of ground_fog_layers (p.563) 


The else block in lines 34-53 is essentially the same as the ground_fog shader. After checking to 
see if the ray has left the scene without striking any objects (state->dist is equal to zero) 
in line 20, the else if block in lines 23-32 evaluates the tinting colors full_fog marker 
and partial_fog_marker for use in the shader’s debugging mode. The world space point 
world_point is derived from state->point in line 28. The y component of world_point is then 
used to decide whether one of the two tinting colors should modify the background color stored 
in result. 
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For complex shader effects, it may be useful to build in analysis and debugging techniques like 
this from the very beginning in shader development. These strategies in a shader are the visual 
equivalent to statements in traditional software development that print out intermediate variable 
values to determine whether the program is behaving as expected. 


22.4 Varying the ground fog layer positions 


With the camera immersed in the partial fog layer we can fill the entire image with fog but still 
allow for different densities based on height. 


camera "cam" 
eutput "“rgba" "Cit" 
"atmosphere 6.tif" 
focal 1.5 


aperture 1 

aspect 1 
resolution 300 300 
volume 


"ground fog" ( 
"fog coloxs”® 1 1 .3, 
"fade start" -.2, 
"face ena” 1.6, 
"fog density” .5, 
"unit density" .6, 
"march_increment" 
end camera 


Figure 22.18: Expanding the vertical range within which the fog dissipates 


By minimizing the difference between the fade_start and fade_end parameters, we can define 
a sharper boundary for the fog. Adjustments to the density also allow for control of the degree 
of background visibility throughout the fog region. 

camera "cam" 


Sha et et — 
"“eqgna” "tar 


output 
=i "atmosphere _7.tif" 
focal 1.5 
aperture 1 
aspect 1 
resolution 300 300 
volume 
"ground fog" ( 
"leq color" 
"fade start" 
"fade end*® -. 1, 
"fog density" .38, 
"unit density" .7, 
"march increment" 
end camera 
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Figure 22.19: Compressing the vertical fade range and lessening the maximum density of the fog 


To construct more complex volume effects, in the next chapter we’ll associate differing degrees 
of density with positions within objects themselves. 
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Chapter 23 


Volumetric effects 


In the last chapter, we attached a volume shader to the camera, giving us a final opportunity 
to modify the eye ray color before the sample is stored for later filtering to create a pixel. In 
this chapter, we’ll attach volume shaders to objects, transforming them into three-dimensional 
regions within which we can control the modification of the background color as the ray passes 
through the object. 


23.1 Rays in volume shaders 


A volume shader is defined as part of the material of an object. In the simplest case, the volume 
shader modifies an input color defined by the shader’s result argument. We can think of the 
result value as the color on the other side of the object that is changed by the obscuring or 
tinting effect of the object’s contents. This is similar to a volume shader attached to the camera, in 
which the initial value of the result argument is the final value calculated by the eye ray. 


Rather than thinking about the ray striking the surface of an object, we consider the path of the 
ray through the object, as if the object is perfectly transparent and without any refraction of the 


ray. 


Figure 23.1: An eye ray passing through an object volume 


Prog 250, 3.10. Volume 
Shaders 


Prog 85, 2.7.1.1. Sampling 
Quality 


Rend 171, 6.3. Ray Marching 
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The state argument to a volume shader attached to an object contains the point at which the ray 
enters the volume and its direction, as well as the length of the ray segment. 


state->org Entry point of the ray into the volume 
state->dir Direction of the ray 
state->dist Length of the ray from the entry to exit intersections 


Figure 23.2: Fields in miState used in volume shaders 


These fields in miState define the geometric configuration we can use in a volume shader. 


<[ state->dir 


state->corg 


Figure 23.3: State variables for the ray direction, intersection and length in the volume 


To determine the cumulative effect of a ray’s passage through the volume object, we can use the 
ray marching technique from the last chapter. Here, however, the march points only exist within 
the object itself, which serves as the container, or ull, for the volume. We'll assume that we can 
also determine a density value for each march point along the ray. 


Figure 23.4: Sample points along the ray inside the volume 


To determine points along the ray, we can use the utility function miaux_point_along_ray from 
the last chapter (page 362), since volume shaders attached to objects also make use of state->org, 
state->dir and state->dist. With this function at the heart of our volume shader, we can 
determine a set of march points for each ray that passes through the object. The volume is then 
sampled in all three dimensions: the two dimensional grid of the samples of our eye rays, and the 
third dimension of the samples along each ray through the volume. 
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Figure 23.5: Sample points along all rays inside the volume 


All the shaders in this chapter will sample the object volume in this manner as we develop 
increasingly complex methods for defining the density values it contains. 


23.2. Using a threshold value in the volume 


For our first volume shader, we’ll define a surface in the space by returning a color from our 
volume shader when the accumulated density of the march points has passed a given threshold. 
To do this, we'll march along the ray, but depending upon the density that the ray encounters, 
we may not completely traverse the volume. If our threshold is zero, then our rendered image 
will produce the silhouette of non-zero densities. 


Figure 23.6: A spherical volume function and the first point encountered by the ray 


The density function for our threshold determination, miaux_threshold_density, uses the 
standard library function mi_vector_dist to find the distance of a given point to the center of a 
sphere and compares this to a given radius. If the point is within the radius, then the full density 
value for that march increment is returned. If the point is outside the sphere, there is a density 
value of zero. 
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miScalar miaux_threshold_ density ( 
miVector *point, miVector *center, miScalar radius, 
miScalar unit _density, miScalar march_increment) 


miScalar distance = mi_vector dist(center, point); 
if (distance <= radius) 

return unit _density * march_increment; 
else 

return 0.0; 


COOWMWNHDU PWN EP 


f 


Figure 23.7: Function miaux_threshold_density 


The various arguments to the density function are defined as parameters to the volume shader. 
By default, the value of the density_threshold parameter is zero, so that any density value in 
the volume will return the color parameter value. 


declare shader 
color "threshold _volume" ( 
color "color" default 11141, 
vector "center" default 0 0O 0, 
scalar "radius" default 1, 
scalar "density threshold" default 0, 
scalar "unit density" default 1, 
scalar "march_increment" default 0.1 ) 
end declare 


Figure 23.8: Shader declaration of threshold_volume (p.564) 


Rendering an image with this volume shader, we see a sphere that represents the positions in the 
volume with a non-zero density (greater than the density_threshold value, which is 0.0). 


material "sphere volume" 
volume "threshold volume" ( 
‘eqglor” .7 .7 1, 
"radius" 1, 


"unit density" 1, 

"density threshold" 0, 

"March increment" .1 ) 
end material 


Figure 23.9: A sphere defined by volume shader threshold_volume 


Notice that the material does not contain an initial shader to define the material’s color—the 
material definition begins immediately with the volume statement and the definition of the 
volume shader. 
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To visualize the hull object, we can use a separate transparent object with a contour shader for 
its outline. The transparent object must be slightly different in size so that its triangles and those 
of the hull object are not coplanar. 


material "outline" 
"transparent" ( 
"transparency" 
contour “cc contour” 
Pera ~ AS 
Meolor’ 1.00 1 


end material 


material "sphere volume" 
volume "threshold volume" ( 

"OOLOE™ oF 3 TF dy 
tyadius”™ ‘I, 
"unit density" 1, 
"density threshold" 0, 
‘march inerement™ -.1.') 

end material 


Figure 23.10: The hull object that contains the ray march 


With a non-zero density threshold, the ray must pass through some part of the sphere to 
accumulate sufficient density for the shader to return a color. Setting the density_threshold 
parameter in Figure 23.11 to 1.6, the resulting sphere is smaller than in Figure 23.9 with its 


threshold of 1.0. 


material "sphere volume" 
volume "threshold volume" ( 
SOLO el FD, 
iradius”" 1 


"unit density" 1, 

"density threshold" 1.6, 

"march iInerement"™ .1'') 
end material 
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Figure 23.11: A sphere defined by shader threshold_volume with a smaller density threshold 


The structure of the volume shader functions in this chapter is dominated by the loop of the 
march points along the ray. 
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struct threshold volume { 
miColor color; 
miVector center; 
miScalar radius; 
miScalar density threshold; 
miScalar unit density; 
miScalar march increment; 
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miBoolean threshold volume ( 
miColor *result, miState *state, struct threshold volume *params ) 
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miScalar march increment = *mi_eval_ scalar (&params->march_increment) ; 
miColor *color = mi_eval_color(&params->color) ; 

miVector *center = mi_eval_vector(&params->center) ; 

miScalar radius = *mi_eval_scalar(&params->radius) ; 

miScalar unit density = *mi_eval_ scalar (&params->unit density) ; 

miScalar density threshold = *mi_eval_scalar(&params->density threshold) ; 
miScalar distance, accumulated density = 0.0; 

miVector march _point, internal_center; 

mi_ point from_object (state, &internal_ center, center) ; 
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for (distance = 0; distance < state->dist; distance += march increment) { 
miaux_ march point (&march point, state, distance) ; 
accumulated density += 
miaux_threshold _density(&march_point, &internal_center, radius, 
unit density, march_increment) ; 
if (accumulated density > density threshold) { 
miaux_ copy _color(result, color) ; 
break; 
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} 
} 


return miTRUE; 
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Figure 23.12: Shader source of threshold_volume (p.564) 


In lines 13-20 we acquire the parameter values and define some local variables, as well as initialize 
the accumulated_density to 0.0 in line 19. We will be using the internal coordinate space during 
the ray march, so we transform the center parameter to internal space in line 21. The ray- 
marching loop is lines 23-32, with the calculation of the accumulated density along the ray in 
lines 25-27. We’ll see this structure in all of the shaders in this chapter, in which we iterate along 
the ray by the march increment until we have traversed the full distance (the length state->dist) 
or we satisfy some condition, like the test to see if the density threshold has been exceeded in 
line 28. If the condition is never satisfied, then the initial value of the result argument, the 
background color, is returned unmodified as the shader’s result. 


23.3. Cumulative density for a ray in the volume 


In the previous shader, we simply returned the color passed as an input parameter (the copy to 
result in line 29) if the threshold density value was exceeded. The next volume shader will 
actually use the accumulated values to define the output color for the material. 


As before, we'll consider the values in a spherical region, but we may end up passing through the 
entire volume, and will need to consider the relationship of the background color to a color we 
define from the accumulated density. 
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Figure 23.13: A spherical volume function with its enclosed sample points 


The density function miaux_density_falloff uses miaux_fit to calculate density values that 
scale from 1.0 at the center of a spherical region to 0.0 at the surface of the sphere defined by its 


radius. 


miScalar miaux_density falloff ( 
miVector *point, miVector *center, miScalar radius, 
miScalar unit density, miScalar march_increment) 


return march_increment * unit density * 
miaux fit clamp(mi_vector dist(center, point), 0.0, radius, 1. 


Figure 23.14: Function miaux_density_falloff 


Unlike the threshold_volume shader, we will not provide a density threshold parameter, but the 
unit_density and march_increment parameters are defined as before. 


declare shader 
color "density volume" ( 
color  "cOLor” default 1 11 ii, 
vector "center" default O O O, 


scalar "radius" default 1, 

scalar "unit density" default 1, 

scalar "march_increment" default 0.1 ) 
end declare 


Figure 23.15: Shader declaration of density_volume (p.566) 


Now the density value is used to scale the input color, blending it with the background color if 
the density is less than 1.0. 
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material "sphere volume" 
volume "density volume" ( 
Mepilor” .Pictt l; 


'radius" 1, 

"unit density" 1, 

"March increment" .05 
end material 


Figure 23.16: A sphere defined by volume shader density_volume 


The structure of density_volume is similar to the previous shader, but differs in the way the 
march loop is terminated and how the accumulated density value is used. 


struct density volume { 
miColor color; 
miVector center; 
miScalar radius; 
miScalar unit density; 
miScalar march_increment ; 


hy 


miBoolean density volume ( 
miColor *result, miState *state, struct density volume *params ) 
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miScalar march_increment = *mi_eval_scalar(&params->march_increment) ; 
miColor *color = mi_eval_color(&params->color) ; 

miVector *center = mi_eval_vector(&params->center) ; 

miScalar radius = *mi_eval_scalar(&params->radius) ; 

miScalar unit_density = *mi_eval_scalar(&params->unit_ density) ; 
miScalar distance, accumulated density = 0.0; 

miVector march point, internal _ center; 

mi_point from_object (state, &internal_center, center) ; 
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for (distance = 0; distance <= state->dist; distance += march increment) { 
miaux_march point (&march point, state, distance) ; 
accumulated density += 
miaux_density falloff(&march_point, &internal_ center, radius, 
unit_density, march_increment) ; 
if (accumulated density > 1.0) { 
accumulated density = 1.0; 
break; 
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} 
} 
if (accumulated density > 0.0) 
miaux_blend_colors(result, result, color, 1.0 - accumulated density) ; 
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return miTRUE; 
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Figure 23.17: Shader source of density_volume (p.566) 
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In lines 23-25 the density is calculated and added to accumulated_density as before. However, 
if the accumulated density is greater than 1.0, the volume is fully opaque along the ray at that 
point, so there is no need to accumulate further density values, and the ray marching is terminated 
early. 


If the ray has accumulated any non-zero density values along its traversal (line 31), then in line 32 
it treats that density value as the weighting factor in a blend between the background and the 
color parameter to the shader. Handling the background color is part of the volume shader’s 
contract, and in this case we can use the density as if it were the alpha value in a traditional 
compositing operation. 


23.4 Illumination of samples in the volume 


In the previous shaders, no lights were used to define the appearance of the volume (though the 
background objects were lit and assigned a lambert shader in their material). If we consider a 
light shining on the volume, a march point ona ray is blocked by the accumulated density within 
the volume between it and the light. 
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Figure 23.18: Adding up the density between a sample point and a light 


Each point along the ray will be similarly lit. The density encountered by the ray will attenuate 
this series of color values produced by the color of the light. 


Figure 23.19: Calculating the illumination values for all the samples along a ray 
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The shader definition of illuminated_volume will be the same as density_volume but with the 
addition of an array of lights. 


declare shader 


color "illuminated volume" ( 
color "color" default 11114, 
vector "center" default 0 0O O, 


scalar "radius" default 1, 
scalar "unit density" default 1, 
scalar "march increment" default 0.1, 
array light "lights" ) 

end declare 


Figure 23.20: Shader declaration of illuminated_volume (p.567) 


The lights are placed on the either side of the object so that we can see the colored shadows 
produced by the object as it blocks both lights. 


options "opt" 
object space 


eontrast .1 4.1.1 
samples 0 2 
volume on 
shadow segments 
end options 


Light "ligne" 
"point light _shadow" ( 
"lignt color" .7 27 «3 | 
origin 15 0 
end light 


instance "light1-i" "light1" end instance 


light "light2" 
"point light shadow" ( 
Wiagkht @Golor® «<2 «3 «7 ] 
origin -1 5 0 
end light 


instance "light2-i" "light2" end instance 


material "sphere volume" 
volume "illuminated_volume" ( 
"color" 1 i i, 
'raniuea" 1, 
"unit density" 1, 
"march inerement" .05, 
hlightes" ["laghti-i", "laght2-2.") } 
end material 


Figure 23.21: Lighting with shadows on a sphere volume 


The sphere_volume material only contains a volume shader—where are the shadows coming 
from? In shadow segments mode (set in the options block), the volume shader is automatically 
used as a shadow shader when a light is sampled with mi_sample_light. This means that shader 
illuminated_volume will need to check the ray type, and attenuate the result if it is a shadow 
ray. If it’s not, then the light values will be accumulated to determine the color of that point 
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in the ray march. These light values will be attenuated from the same shader called in shadow 
mode. 


23.4.1 Fractional occlusion 


To determine how much a light is blocked at a given point in the volume, we'll define the function 
miaux_fractional_occlusion_at_point. It calculates an occlusion factor, the degree to which 
a point is blocked by the accumulated density between it and another point. 


miScalar miaux_fractional_ occlusion at _point ( 
mivector *start_point, miVector *direction, 
miScalar total distance, miVector *center, miScalar radius, 
miScalar unit density, miScalar march_increment) 


miScalar distance, occlusion ~0e 

miVector march point; 

mi_vector_ normalize (direction) ; 

for (distance = 0; distance <= total distance; distance += march_increment) { 


miaux point along vector(&march_ point, start _point, direction, distance) ; 
occlusion += miaux_ threshold density(&march point, center, radius, 
unit density, march_increment) ; 

if (occlusion >= 1.0) { 

occlusion = 1.0; 

break; 
} 

} 


return occlusion; 


Figure 23.22: Function miaux_fractional_occlusion_at_point 


This function is very similar to the previous shaders. In lines 9-17 the ray marching loop is 
structured as before, using the threshold density function for its calculations. However, the 
ray along which density values are accumulated is provided as the direction argument to the 
function. 


23.4.2 Total light at a point in the volume 


Given the occlusion used in the shadow mode of shader illuminated_volume, what is the total 
light at a point in the volume? We'll loop over the lights, accumulating their values in the same 
way we did for the standard illumination models in Chapter 12. 
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void miaux_total_ light _at_point ( 
miColor *result, miVector *point, miState *state, 
miTag* light, int light count) 


miColor sum, light color; 

int i, light_sample count; 

miVector original point = state->point; 
state->point = *point; 


miaux_ set channels(result, 0.0); 
for (i = 0; i < light count; i++, light++) { 


miVector direction_to_light; 
light _sample_ count = 0; 
miaux_ set channels(&sum, 0.0); 
while (mi_sample light (&light_ color, &direction_to_light, NULL, 
state, *light, &light sample count) ) 
miaux add scaled _color(&sum, &light_color, 1.0); 


if (light sample count) 
miaux_ add scaled _color(result, &sum, 1/light_sample_ count) ; 


} 


state->point = original point; 


Figure 23.23: Function miaux_total_light_at_point 


Function miaux_total_light_at_point will be called at each point during the ray march. In 
lines 11-21 we loop over the lights, sampling them in lines 15-16. The shadow mode of shader 
illuminated_volume is responsible for attenuating the light color returned by mi_sample_light 
based on the density of the volume. 


We are calculating the total light at a point, but at which point? Function mi_sample_light 
receives the miState pointer as an argument, and the light value is calculated at state->point. 
To determine the light value at an arbitrary point in space, we need to first set state->point to 
the desired point in line 8 before we call mi_sample_light, and then restore the original value of 
state->point afterwards in line 22. 


23.4.3 Accumulating and blending volume colors 


We’ll encapsulate the accumulation of density values interpreted as colors during the ray march 
with function miaux_add_transparent_color. The increasing opacity of the volume will be 
stored in the alpha component of the color. 


void miaux_add_transparent_color ( 
miColor *result, miColor *color, miScalar transparency) 


miScalar new_alpha = result->a + transparency; 
if (new_alpha > 1.0) 


transparency = 1.0 - result->a; 
result->r += color->r * transparency; 
result->g color->g * transparency; 
result->b color->b * transparency; 
result->a transparency; 


Figure 23.24: Function miaux_add_transparent_color 


Once we have finished determining the color of the volume, we will need to blend the resulting 
density color with the background color using the density color’s alpha value. 
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void miaux_alpha_ blend colors ( 


{ 


miColor *result, miColor *foreground, miColor *background) 


double bg fraction = 1.0 - foreground->a; 

result->r = foreground->r + background->r * bg fraction; 
result->g = foreground->g + background->g * bg fraction; 
result->b = foreground->b + background->b * bg fraction; 


Figure 23.25: Function miaux_alpha_blend_colors 


In blending the foreground volume color over the background, we need to account for the scaling 
of the red, green, and blue components in miaux_add_transparent_color by the transparency 
stored in the alpha channel. In miaux_alpha_blend_colors, we scale the background by the 
inverse of the foreground’s alpha, but we don’t need to scale the foreground. In this kind 
of compositing operation, we say that the color channels have been premultiplied by the 
alpha. 


23.4.4 The illuminated volume 


In shader illuminated_volume, we’ll use miaux_fraction_occlusion_at_point in the shader’s 
shadow mode and miaux_total_light_at_point during the ray march to accumulate the ray’s 
color values. 
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struct illuminated volume { 
miColor eolor; 
miVector center; 
miScalar radius; 
miScalar unit density; 
miScalar march increment; 
Lae i. Tight ; 
int n_ light; 
miTag light [1]; 


ba 


miBoolean illuminated volume ( 
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miColor *result, miState *state, struct illuminated volume *params ) 


{ 


miScalar radius, unit _density, march_increment, density, distance; 


miVector *center, internal _center, march point; 
int light count; 
miTag *light; 


if (state->type == miRAY_ LIGHT) 
return miTRUE; 


center = mi_eval_vector(&params->center) ; 
radius = *mi_eval_ scalar (&params->radius) ; 


unit density = *mi_eval_ scalar (&params->unit_density) ; 
march increment = *mi_eval_ scalar (&params->march_increment) ; 
mi point from_object(state, &internal_ center, center) ; 


if (state->type == miRAY SHADOW) { 


miScalar occlusion = miaux_fractional_occlusion_at_point 


&state->org, &state->dir, state->dist, 


( 


&internal center, radius, unit density, march_increment) ; 


miaux_ scale color(result, 1.0 - occlusion) ; 
} else { 
miColor *color = mi_eval_color(&params->color) ; 
miColor volume_color = 16,0,0,0), light color, point _color; 
void* original state_pri = state->pri; 


state->pri = NULL; 


miaux_light_array(&light, &light_count, state, 


&params->i light, &params->n_light, params->light) ; 


for (distance = 0; distance <= state->dist; distance += march_increment) { 


miaux_ march point (&march_ point, state, 
density = miaux_threshold density ( 


&march point, &internal center, radius, 


unit _density, march_increment) ; 
if (density > 0.0) { 
miaux_total_light_at_point ( 


&light color, &march_point, state, 


distance) ; 


light count) ; 


miaux_ multiply _colors(&point_color, color, &light_color) ; 
miaux_add_ transparent _color(&volume_color, &point_color, density) ; 


} 


if (volume _color.a == 1.0) 
break; 


} 


miaux_alpha_blend_colors(result, &volume_color, 


state->pri = original state pri; 


} 


return miTRUE; 


Figure 23.26: Shader source of illuminated_volume (p.567) 
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To avoid multiple rays sent through the volume by recursive calls to the light shader during light 
sampling, we first check the type of ray that invoked the shader in line 20, and immediately return 
if it’s a light ray. Our standard ray marching loop is lines 42-55. But we are also determining 
the shadowing value, and the conditional of the if statement in line 29 which checks the type of 
ray allows this shader to be used for shadows, too. In shadow mode, we calculate the degree to 
which the volume occludes the current point in lines 30-32 and use that value to attenuate the 
input color in line 33. 


In lines 44-46 we find the density in the ray march as before. However, if the density is greater 
than 0.0, we multiply our input parameter color by the light color calculated in lines 48-49, 
resulting in point_color in line 50. We then add this color to the accumulating volume_color in 
line 51, taking the density into account as a transparency factor. In line 56, we blend the volume 
color with background as before. 


For volume shaders, we are sampling the light not for a geometric surface but for march points 
along the ray. We therefore need to disable the test mental ray performs to see if the normal 
of the current geometric primitive is facing away from the light. Normally, mental ray would 
ignore the light in that case. By setting state->pri to NULL in line 38, we force consideration of 
all lights in the scene. In line 57, we restore the previous value of state->pri saved in line 37. 
Temporarily modifying a value in the state structure is a technique that can be used in various 
ways. In the next shader, we’ll even modify state->point. 


23.5 Defining the density function with a shader 


As we have begun to use our density function in several places for the determination of density 
as well as light occlusion, it has become awkward and inflexible to repeat that function. If we 
define the density function as a shader, then we can create a generic volume shader for the ray 
marching process and modify its behavior simply by specifying a different density shader as a 
parameter. 


The first density shader we’ll define, spherical_density, will be similar in intent to the volume 
shader threshold_density, returning a value of 1.0 if the point is within the radius of a sphere, 
and 0.0 if outside. 


declare shader 
scalar "spherical density" ( 


vector "center" default 0 O 0, 
scalar "radius" default 1 ) 
end declare 


Figure 23.27: Shader declaration of spherical_density (p.568) 


In the spherical_density shader, we aren’t concerned with anything other than the calculation 
of the scalar density value. By transforming the arguments of a standard C function into the 
parameters of a shader, we can convert any function into a shader and use its value as the input 
to the parameter of any other shader. 


Prog 210, 3.4.4. Intersection 
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struct spherical density { 
miVector center; 
miScalar radius; 


bi 


miBoolean spherical density ( 


{ 


miScalar *result, miState *state, struct spherical density *params ) 
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miVector *center = mi_eval_vector(&params->center) ; 
miScalar radius = *mi_eval_ scalar (&params->radius) ; 
miVector point; 

mi vector to world(state, &point, &state->point) ; 
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1f (mi_vector dist(center, &point) <= radius) 
*“result:.= 1..0; 

else 
*result O03 
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return miTRUE; 
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Figure 23.28: Shader source of spherical_density (p.568) 


The spherical_density shader returns a scalar value, so the type of the first argument in line 7 
is miScalar. The center of the sphere is passed as a parameter, and evaluated in line 9. But how 
do we know the position of the current march point? We can’t pass it as a parameter—it will be 
different for every ray. This shader assumes that the current point is state->point, and we’ll 
set it explicitly in the volume shader when we call this density shader there. 


declare shader 
color "parameter volume" ( 
color “color" default 11 ii, 
shader "density shader", 


scalar "unit density" default 1, 
scalar "march_increment" default 0.1, 
array light “Lighte”":) 

end declare 


Figure 23.29: Shader declaration of parameter_volume (p.569) 


Notice that the density_shader parameter is declared to be of type shader. By defining a shader 
in the scene, we can pass it by its name to another shader as a parameter. 
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shader "sphere" 
"Spherical density" 
"radius". 1, 
"center" 0 


material "sphere volume" 


volume "parameter volume" ( 
"density shader" "sphere", 
"unit density" 1, 
"march increment" .05, 
eLigice -L 2agnee~s", "Laight2=2.") 2 
end material 


Figure 23.30: Defining density with shader spherical_volume 


The definition of shader sphere in Figure 23.30 provides parameter values for the shader that 
defines the density function, spherical_density, and adds this definition to the scene database. 
In the material, then, the volume shader can reference this shader definition by name as the value 
of the density_shader parameter of shader parameter_volume. 


How are shaders accessed in a shader? The shader is represented as a tag, and called by the API  Prog316, 3.26. Functions for 
library function mi_call_shader_x. Shaders 


miScalar miaux_fractional_ shader occlusion at point ( 
miState *state, miVector *start point, miVector *direction, 
miScalar total distance, miTag density shader, 
miScalar unit_density, miScalar march_increment) 


miScalar density, distance, occlusion 0; 
miVector march point; 
miVector original point = state->point; 
mi_vector_ normalize (direction) ; 
for (distance = 0; distance <= total distance; distance += march_increment) { 
miaux_point_ along _vector(&march point, start point, direction, distance) ; 
state->point = march point; 
mi_call shader_x((miColor*) &density, miSHADER MATERIAL, state, 
density shader, NULL) ; 
occlusion += density * unit density * march increment; 
if (occlusion >= 1.0) { 
occlusion = 1.0; 
break; 


state->point = original point; 
return occlusion; 


Figure 23.31: Function miaux_fractional_shader_occlusion_at_point 


Function miaux_fractional_shader_occlusion_at_point is a slight modification and exten- 
sion of function miaux_fractional_occlusion_at_point. It takes an additional argument for 
the shader in line 3, density_shader, of type miTag. To acquire the density value, the function 
mi_call_shader_x is called with the density shader tag as an argument. Notice that the function 
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mi_call_shader_x requires an initial argument of type miColor. Since spherical_density has 
a result type of miScalar, we cast the result argument in line 13 to a pointer to miColor. The 


structure of the rest of the function is the same as before; it only differs in the way that the density 
value has been acquired. 


With a function that takes a shader as an argument we can convert shader illuminated_volume 
to shader parameter_volume. 


declare shader 
color "parameter volume" ( 
color-"color" default +2 2-7. 
shader "density shader", 


scalar "unit density" default..1, 
scalar "march increment" default 0.1, 
array light "lights" ) 

end declare 


Figure 23.32: Shader declaration of parameter_volume (p.569) 


In the .mi declaration of parameter_volume, the density shader is of type shader. In C, the 
declaration of a shader tag is type miTag. 


struct parameter volume { 
miColor color; 
miTag density shader; 
miScalar unit_density; 


miScalar march increment; 
int 1 Lights 
int n light; 
miTag Ligne [1] ; 


Figure 23.33: Source code of struct parameter_volume (p.569) 


Shader parameter_volume checks for shadow mode inthe same manner as illuminated_volume. 
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miBoolean parameter volume ( 


{ 


miColor *result, miState *state, struct parameter volume *params ) 


miScalar unit density, march increment, density; 
miTag density shader, *light; 
int light count; 


if (state->type == miRAY LIGHT) 
return miTRUE; 


density shader = *mi_eval_tag(&params->density shader) ; 
unit density = *mi_eval_ scalar(&params->unit density) ; 
march increment = *mi_eval scalar (&params->march_increment) ; 
miaux_light_array(&light, &light count, state, 
&params->1i light, &params->n_light, params->light) ; 


if (state->type == miRAY SHADOW) { 
miScalar occlusion = miaux_ fractional shader occlusion at point ( 
state, &state->org, &State->dir, state->dist, 
density shader, unit density, march _increment) ; 
Miaux scale color(result, 1.0 - occlusion) ; 
} else { 
miColor *color = mi_eval_color(&params->color) ; 
miScalar distance; 
miColor volume color = 10.0, 0, 0%; 14gnt color, por color; 
miVector original point = state->point; 
void* original state pri = state->pri; 
state->pri = NULL; 


for (distance = 0; distance <= state-sdist; distance += march_increment) 
miVector march point; 
miaux_march_ point (&march point, state, distance) ; 
state->point = march point; 
mi_call shader _x((miColor*) &density, 
miSHADER MATERIAL, state, density shader, NULL) ; 

if (density > 0) { 

density *= unit density * march_increment; 

miaux_ total light _at_ point ( 

&laght color, &march point, state, laght, light _count) ; 
miaux_multiply colors(&point color, color, &light_ color) ; 


{ 


miaux_add_transparent_color(&volume_color, &point color, density) ; 


} 


1£ (volume _color.a == 1.0) 
break; 
} 
miaux_alpha_blend_colors(result, &volume_color, result) ; 
state->point = original point; 
state->pri = original state pri; 
} 


return miTRUE; 


Figure 23.34: Shader source of parameter_volume (p.569) 


The density shader tag is evaluated in line 11 and is used twice in parameter_volume. In shadow 
mode it is passed as an argument to miaux_fractional_shader_occlusion_at_point in lines 18- 
20. When the color of a point in the volume is calculated during ray marching, it is evaluated 
directly with mi_call_shader_x in lines 34-35. 


Now that we have the framework for the ray marching, we can use arbitrary shaders that will 
represent the density of the space. For example, shader radial_falloff defines a center point 
and a radius, and the density values at those points. 
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declare shader 
scalar "radial falloff" ( 
vector "center" default 0O O O, 


scalar "radius" default 1, 

scalar "center value” default 1, 

scalar "radius _ value" default 0 ) 
end declare 


Figure 23.35: Shader declaration of radial_falloff (p.571) 


The radial_falloff shader doesn’t explicitly refer to density, it just maps points in space to a 
scalar value. 


struct radial falloff { 
miVector center; 
miScalar radius; 
miScalar center value; 
miScalar radius value; 


be 


miBoolean radial falloff ( 
miScalar *result, miState *state, struct radial falloff *params ) 
{ 


miVector *center = mi_eval_ vector (&params->center) ; 

miScalar radius = *mi_eval_scalar(&params->radius) ; 

miScalar center value = *mi_eval_ scalar (&params->center_ value) ; 
miScalar radius value = *mi_eval_ scalar(&params->radius_ value) ; 
miScalar distance; 

miVector point; 


mi vector to world(state, &point, &state->point) ; 
distance = mi_vector dist(center, &point) ; 
*result = miaux_sinusoid fit clamp ( 

distance, 0.0, radius, center value, radius value) ; 


return miTRUE; 


Figure 23.36: Shader source of radial_falloff (p.571) 


We’ll use shader radial_falloff as our density function in the shader definition of sphere that 
We pass as a parameter to parameter_volume. 


shader "sphere" 
"reeia. Tallori™ | 
tradiue" 1, 
"Senter" 0 .1 6, 
‘eenter value? 1.2) 


material "sphere volume" 
volume "parameter volume" ( 
"density shader" "sphere", 
"unit density" 1, 
"March increment" .05, 
"iagnte" ("irgpti-1", “Lagne2-1") ) 
end material 


Figure 23.37: Defining density with shader radial_falloff 
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23.6 Using voxel data sets for the density function 


Now that we’ve generalized the density function as an input parameter of type shader, we can 
define more complex volume effects just by defining new density shaders. 


For example, medical imaging technologies can produce three-dimensional arrays of measured 
densities, a spatial equivalent to X-ray images. By analogy to the invention of the word “pixels” 
(derived from “picture elements”), these volume data sets have been called voxels. 


You can think of pixels as a rectangular array of numeric values. 
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Figure 23.38: Pixels as a plane of numbers 


Extending this idea into three dimensions, we can think of a voxel data set as a series of these 
numeric arrays. 
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Figure 23.39: Voxels as a set of planes of numbers 


390 23 Volumetric effects 


If we define a shader that can determine density values based on voxel data sets, then we can use 
that shader as input to parameter_volume. 
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Figure 23.40: A voxel data set as density measures in a volume 


For the calculation of the value for each ray, we’ll sample the density of the volume using the 
voxel data. The number of samples we take and the number of samples represented by the voxel 
data set do not need to be the same. 


Figure 23.41: Raymarching through a voxel data set 


For our voxel density shader, we’ll define a simple data format for voxel data sets stored as files. 
Our voxel file will contain: 


1. The width, height and depth of the data set in ASCII format as three integers separated by 


whitespace; and 
2. The data as floating-point values in a continuous block. 


The function miaux_read_volume_block reads the data in the voxel file, passing the dimensions 
and the data block itself back from the function through pointer arguments. 
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void miaux_read_volume_block ( 
char* filename, 
int *width, int *height, int *depth, float* block) 


int count; 
FILE* fp = fopen(filename, "r") ; 
if (fp == NULL) { 


mi fatal ("Errer opening file -"“ts".",- filename) ; 
} 
fscanf(fp, "td td td ", width, height, depth) ; 
count = (*width) * (*height) * (*depth) ; 
mi _progress("Volume dataset: *dx%dx%d", *width, *height, *depth) ; 
fread(block, sizeof(float), count, fp); 


Figure 23.42: Function miaux_read_volume_block 


The data will be stored in our shader in a struct called voxel_data. 


1 typedef struct { 

2 int width, height, depth; 

3 Float block [MAX DATASET SIZE] ; 
4 } voxel data; 


Figure 23.43: Struct for storage of voxel data in shader (p.572) 


Acquiring individual voxel values uses the dimension fields of the voxel_data struct to determine 
the offset to the desired array element. We’ll define function miaux_voxel_value to do this 
lookup. 


float voxel value(voxel_ data *voxels, float x, float y, float 2z) 


{ 


return voxels->block [ 


((int) (y + .5)) * voxels->height + 


i 
2 
3 
4 ((int) (z + .5)) * voxels->depth * voxels->height + 
5 
6 ((int) (x +- i577] ; 

7 


} 


Figure 23.44: Shader source of voxel_density (p.572) 


Function miaux_voxel_value takes as arguments the floating-point coordinates of a position in 
the voxel block. Here, we just truncate the floating point value to get an array index. If we later 
need a better approximation of a value in the voxel set (for example, by a weighted average of the 
voxels around the desired point), we could replace the body of this function without requiring 
structural changes to the rest of the shader code. 


We will map the block of voxel data to a region of space by defining the minimum and maximum 
coordinates into which the voxel data should be scaled. 
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declare shader 
scalar "voxel density" ( 
string "filename", 


vector "min_point" default -1 -1 -1, 
vector "max_point" default 111, 
color "color®” defauit.1 i- 1,..) 

end declare 


Figure 23.45: Shader declaration of voxel_density (p.572) 


Prog 403, 3.27. Initialization | We only want to read the voxel data file once, when we first call the shader, so we need to define 
and Cleanup ‘nit f : . hich the d : dand d 
an init function in which the data is read and stored. 


miBoolean voxel density init ( 
miState *state, struct voxel density *params, 
miBoolean *instance init required) 


if (!params) { /* Main shader init (not an instance): */ 
*instance init required = miTRUE; 
} else { /* Instance initialization: */ 
char* filename = 
miaux_ tag to string(*mi_eval_ tag(&params->filename_tag), NULL) ; 
if (filename) { 
voxel data *voxels = 
miaux user memory pointer(state, sizeof (voxel data) )j; 
miaux_read_volume_block ( 
filename, &voxels->width, &voxels->height, &voxels->depth, 
voxels->block) ; 
mi progress ("Voxel dataset: %dx%dx%d", 
voxels->width, voxels->height, voxels->depth) ; 
} 
} 


return miTRUE; 


Figure 23.46: Source code of init shader of voxel_density (p.572) 


In lines 11-12 we use the utility function developed in Chapter 21 to simplity acquiring the user 
pointer, miaux_user_memory_pointer. Because this allocates memory in our init function, we 
must define an exit function to deallocate it. As in Chapter 21, we'll use the utility function 
miaux_release_user_memory. 


miBoolean voxel density exit (miState *state, void *params) 


{ 


i. 

Pe 

3 return miaux_release_user_ memory ("voxel density", state, params); 
4 


} 


Figure 23.47: Source code of exit shader of voxel_density (p.572) 


We don’t want to look up a density value in the voxel block if we are outside the hull defined by the 
min_point and max_point parameters, so we'll define miaux_point_inside for that check: 
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miBoolean miaux_point _inside(miVector *p, miVector *min_p, miVector *max_p) 


{ 


return p->x >= min _p->x && p->y >= min_p->y && p->Z >= min_p->z && 
p->xX <= Max_p->xX && P->y <= Max _p->y && P->Z <= MAaX_P->Z; 


Figure 23.48: Function miaux_point_inside 


Shader voxel_density finds the nearest sample in the block for the resulting density value. 


miBoolean voxel density ( 
miScalar *result, miState *state, struct voxel density *params ) 


miVector *min_point = mi_eval_vector(&params->min_point) ; 
miVector *max_ point = mi_eval_ vector(&params->max_ point) ; 
miVector *p = &state->point; 


if (miaux_point _inside(p, min_point, max_point)) { 
float x, Vi 2; 


voxel data *voxels = miaux_user_ memory pointer(state, 0); 
x = miaux fit(p->x, min_point->x, max_point->x, 0, voxels->width-1) ; 
y miaux fit(p->y, min_point->y, max_point->y, 0, voxels->height-1) ; 
Z = miaux fit(p->z, min_point->z, max_point->z, 0, voxels->depth-1) ; 
*result = voxel value(voxels, x, y, 2); 

} else 
*result ~O; 


return miTRUE; 


Figure 23.49: Source code of shader voxel_density (p.572) 


We first check to make sure the current point is inside the volume hull object in line 8. If it is, 
then we acquire a pointer to the voxel data using miaux_user_memory_pointer in line 10. We 
then find the scaled coordinate position with miaux_fit in lines 11-13 and use that position to 
find the nearest voxel value in line 14. 


In the rendering, you can see the shadows cast through the lower part of the volume by the three 
spherical regions above. 
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shader "spheres" 
"voxel density" ( 
"filename" "three over one.vol" ) 


material "sphere volume" 
volume "parameter volume" ( 
"density shader" "spheres", 
"unit density" 1, 
"march increment" .01, 
"lights" ["laghti-i", “light2-i"] 
end material 


Figure 23.50: Reading a voxel dataset with a shader 


Now both the mechanism of ray marching and the reading of voxel datasets have been abstracted 
into shaders. A different voxel data file produces a different rendered image. 


shader "spheres" 
"voxel density" ( 
"filename" "sphere cloud.vol" ) 


material "sphere volume" 


volume "parameter volume" ( 
"density shader" "spheres", 
‘unit deneszty" ‘1, 
"march increment". .01, 
WLighte" ["lighti-1", "lLight2-1") 
end material 


Figure 23.51: Multiple spheres in a volume data set 


The voxel dataset in these renderings was created by a program that adds arbitrary spherical 
regions to a three-dimensional data array. The reading function for this simple file format could 


be modified to begin exploration of shaders that render medical imaging data saved in files based 
on industry standards. 
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23.7. Summary of the volume shaders 


The shaders in this chapter show a variety of ways in which the technique of ray marching can 
be used in volume shaders in mental ray. 


threshold_volume First march-point along ray to exceed a threshold value 
density_volume Accumulated march-point density along ray 
illuminated_volume Attenuated march-point lighting along ray 
parameter_volume Density function defined by a shader 


The first three shaders are somewhat impractical because the density shader is hard-coded into 
the shader itself. However, by parameterizing the density function as a shader itself, you can 
separate the calculation of the volume function from the way that the volume data should be 
rendered. 


Part 6: Image 


Chapter 24 


Changing the lens 


In most of the scenes we’ve been rendering, we easily slip into a photographic metaphor of image- 
making, with the camera producing an objective record of the objects before it. In this chapter, Prog 275, 3.17. Lens Shaders 
we'll modify the behavior of the camera itself by changing its initial creation of rays in a lens 


shader. 


24.1 Aconceptual model of a camera 


The simplest model of three-dimensional image making in computer graphics is based on a pinhole 

camera. Rather than using a lens, a pinhole camera admits light through a very small opening, Rend 39, 3.1. Pinhole 
the “pinhole.” Light rays entering the pinhole project an image on the back wall of the camera, ieiaiaeaiel 

the viewing plane. Figure 24.1 shows the mental ray pinhole camera model from above, with 

the aperture as a measurement of horizontal distance across the image, and focal as the length 

from the viewing plane to the pinhole. 


viewing plane pinhole “lens” 


aperture 


light 


angle of view 


focal 


Figure 24.1: Pinhole camera model as seen from above with aperture and focal attributes 


The geometry of the pinhole camera is expressed in the camera block in the scene file. The Prog 109, 2.7.2.3. Other 
aperture and focal statements define the lengths in the pinhole camera model in Figure 24.1. eee 
The ratio of the aperture to the focal length defines the angle of view (also called the field of 

view). The aspect and resolution statements control how the projection through the pinhole Rend 40, 3.3. Aspect Ratio 


is mapped to the pixels of the final rendered image. Rend 39, 3.2. Image 
Resolution 


Prog 207, 3.4.3. Rays 


400 24 Changing the lens 


shader "sky" 
"color ramp" 
"colors" 


camera "camera" 
GuEput “xgba" "tit" 


‘lene 1.tie” 
focal 1.5 
aperture 1 
aspect 1 
resolution 300 300 
environment = "sky" 
end camera 


Figure 24.2: Scene rendered with camera defined by its geometrical properties and an environment shader 


In writing lens shaders, however, it is useful to think of the viewing plane as if it is in front of the 
pinhole. Geometrically, if the focal and aperture distances remain the same, the pinhole image 
will also be projected on this plane (but not, conveniently, upside-down). This is the model for 
the mechanical drawing device depicted by Albrecht Direr in Figure 1.2. 


The aperture parameter now describes the width of the viewing plane, with the focal distance 
as a measurement from the eyepoint, state->org, to the viewing plane. 


viewing plane 


Stace->org 


= state->dir 
———— 
[{—____—_—_—_—_—_ 


aperture 
focal 


Figure 24.3: Eye rays starting at state->org and traveling in direction state->dir, seen from above 


Now, rather than thinking of light rays entering the pinhole camera and forming an image on its 
back face, we imagine rays shot from our eye into space to see what color should appear at the 
corresponding intersection point on the viewing plane. Without a lens shader, mental ray only 
considers the transformation matrix in the camera instance to determine the origin and direction 
of eye rays. In a lens shader we can assume control over that default behavior, modifying 
the camera position and direction of individual rays through state variables state->org and 
state->dir. To explore the possibilities of modifying the camera in this way, all the renderings 
in this chapter will differ from Figure 24.2 only in the lens shader attached to the camera. 
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24.2 Shifting the lens position 


In our first lens shader, we'll vary the location of the camera, expressed in a lens shader by 
state->org, by adding a random offset within a range to the z component of the camera’s 
original position. 


Figure 24.4: Moving the origin of the eye ray by redefining its z component 


We'll call this shader streak. The maximum amount of change in z is defined by the parameter 
max_distance. 


declare shader 
color "streak" ( 
scalar "max _distance" default . 


apply lens 

scanline off 

trace on 
end declare 


Figure 24.5: Shader declaration of streak (p.574) 


The declaration of streak in Figure 24.5 includes additional statements to qualify its use in 

the scene. The apply statement, though not used by mental ray, allows applications that 

create graphical interfaces to categorize a shader. Shader declarations can also include option Prog 284, 3.21. Geometry 
requirements that list the option values that are necessary for the shader to execute correctly. In ee 

the case of lens shaders, we must use ray tracing if we modify the initial eye ray’s direction. 


A lens shader is attached to the camera with the lens statement in the camera block, as in 
Figure 24.6. 


Prog 322, 3.26.2. KC 
Functions 


402 24 Changing the lens 


camera "Camera" 
output "rqgba" "Eit" 
‘lens 2.612" 
Focal, 1.5 


aperture 1 
aspect 1 
resolution 300 300 


environment = "sky" 
lens 
"Streak" ( 
"max distance" .2 ) 
end camera 


Figure 24.6: Moving the lens position in space 


The streak shader is a minimal demonstration of the possibilities of a lens shader: modify 
state and begin tracing the eye ray. Without a lens shader, mental ray sends eye rays as if it 
were executing the shader in Figure 24.7, sending each ray from state->org in the direction 
state->dir. 


miBoolean default_lens ( 
miColor *result, miState *state, void *params ) 
{ 


} 


return mi_trace_eye(result, state, &state->org, &state->dir) ; 


Figure 24.7: Default lens behavior expressed as a shader (p.573) 


A lens shader can instead provide new values for the origin and direction of the camera, and then 
initiate ray tracing with the library function, mi_trace_eye. 


struct streak { 
miScalar max_distance; 


by 


miBoolean streak ( 
miColor *result, miState *state, struct streak *params ) 


miScalar max_distance = *mi_eval_scalar(&params->max_distance) ; 
state->org.z += miaux_random_range(-max_ distance, max_distance) ; 
return mi_trace eye(result, state, &state->org, &state->dir) ; 
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Figure 24.8: Shader source of streak (p.574) 


In line 9, we use miaux_random_range to calculate a value within the range specified by the 
max_distance parameter and directly modify the z component of the camera’s position as a field 
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in the miState struct, state->org. We then call mi_trace_eye in line 10 with the modified 
position and original direction. The miBoolean return value of mi_trace_eye is the return value 
of the shader, with the result argument modified to define the color returned by tracing a 


ray. 


Increasing the max_distance parameter further distorts the resulting image. 


Figure 24.9: Moving the origin of the eye ray a greater amount in z 


Because the camera is pointed down the z axis, the center of the image and distant points in the z 
direction are the least affected by this modification of the camera position. 


camera "camera" 
Sueput “"“sgba® "CLE" 
"lens 3.tif" 
focal 1.5 
aperture 1l 
aspect 1 
resolution 300 300 


environment = "sky" 
lens 
"Streak" ( 
"max distance" 1 ) 


end camera 


Figure 24.10: A large value for the max_distance parameter to the streak lens shader 


24.3. Mapping the scene around the camera to a rectangle 


In addition to changing the position of the camera, a lens shader can also modify the direction of 
the primary eye ray the camera sends into the scene. The shader calculates another direction for 
the ray and uses it in the call to mi_trace_eye. Though the ray may be pointed in any direction, 
the resulting color value returned by mi_trace_eye is used for the sample that triggered the 
original shader call. 
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For example, if we think of all possible rays from the camera as a set of points on a sphere, 
we can create an image in which each ray is related, or projected, to a position in the image. 
The equator of the sphere becomes a horizontal line dividing the image in two, and the north 
and south poles are spread out along the top and bottom of the image, respectively. Lines of 
longitude of the sphere are projected to vertical lines in the image; lines of latitude are projected 
to horizontal lines. Because a change in degree measurement in longitude or latitude results in 
the same change in vertical or horizontal distance throughout the image, this relationship is called 
an equirectangular projection. 


360 degrees 
{$2 


180 degrees 


Figure 24.11: Representing ray directions as a sphere around the camera and their projection to a rectangle 


We can define the set of all rays from the camera by sweeping the ray through 360° from left to 
right, and 180° vertically, from straight down to directly overhead. 


go degrees 
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Figure 24.12: All possible ray directions from the camera defined by ray rotations in x and y 


Our lens shader that modifies ray direction based on this equirectangular projection of the sphere 
around the camera is called equirectangular. 
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declare shader 
color "equirectangular" () 
apply lens 


scanline off 
trace on 
end declare 


Figure 24.13: Shader declaration of equirectangular (p.574) 


Rendering the scene from Figure 24.2 with equirectangular we can see a distortion of the 
texture pattern on the plane that surrounds the camera. 


camera "camera" 
output. "sabe" tit" 
"lens 4.tif" 
rocal 1.5 
aperture 1 


aspect 1 
resolution 600 300 
environment = "sky" 
lens 
"equirectangular" 
end camera 


Figure 24.14: The equirectangular projection implemented in a lens shader 


The camera is positioned directly over one of the diamonds in the texture pattern. The top half 
of the color ramp of shader definition sky is fully displayed in the upper half of the image. By 
rendering an image with a pixel width that is twice its height, the size of angular change is the 
same for both the vertical and horizontal directions. 


Shader equirectangular uses a matrix construction function from the shader library to create a 
new direction for the eye ray. 


Prog 202, 3.4.2. Image 
Samples 


Prog 200, 3.4.1. Frame 


Prog 352, 3.26.7. Math 
Functions 
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miBoolean equirectangular ( 


{ 


miColor *result, miState *state, void *params ) 


miMatrix matrix; 
miVector eye ray direction = {0, 0, -1}; 
miScalar x_fractional_ position = 
state->raster x / state->camera->x_resolution; 
miScalar y fractional position = 
state->raster y / state->camera->y resolution; 


OANA NFP WN EH 


Ne) 


mi_matrix_rotate ( 
matrix, 
miaux fit(y fractional position, -M PI/2, M PI/2), 
miaux fit(x_ fractional position, M PI, -M_PI), 
0); 
mi vector transform(&eye ray direction, &eye ray direction, matrix) ; 


PRP PR 
WNHO 


—— 
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return mi_trace eye(result, state, &state->org, &eye ray direction) ; 


PHP Pp 
wow oI 


Figure 24.15: Shader source of equirectangular (p.574) 


In line 5 we define eye_ray_direction, the ray that we'll sweep around the camera based on 
the position of the ray’s sample in the output image. In lines 6-9, we define the fractional 
position of the current sample using its absolute position in pixels (state->raster_x and 
state->raster_y) divided by the size of the image in pixels stored in the camera structure 
in state (state->camera->x_resolution and state->camera->y_resolution). Given this 
fractional position, we can use miaux_fit in lines 13-14 to define the rotation in x and y of 
eye_ray_direction using MPI from math.h. The library function mi_rotate_matrix creates a 
matrix from rotation arguments in radians for x, y, and z. To define the rotation for the vertical 
component of the image, we define a rotation around the x axis in line 13 from -90° to 90° (—7/2 
to 7/2 radians). Similarly, we define a rotation for the horizontal component of the image with 
a rotation around the y axis in line 14 from 180° to -180° (a to —7 radians). Using this matrix, 
we transform eye_ray_direction in line 16 and finish by tracing the eye ray in line 18. 


Given that the entire visible environment is mapped to the space of the image in the equirectangular 
projection, the only control over the composition of the image is the placement of the camera. 
However, an image rendered with the equirectangular projection can also be used as input 
to imaging systems like QuickTime VR, which can simulate camera panning in a virtual 360° 
environment. 


camera "camera" 
sutput "rgba" "CLE" 
"lens 4A.tif" 
focal 1.5 
aperture 1 


aspect 2 
resolution 600 300 
environment = "sky" 
lens 
"equirectangular" 
end camera 


Figure 24.16: Changing the position of the camera in the equirectangular projection 
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24.4 Afisheye lens 


In the streak shader in Section 24.2, we were pretty cavalier about modifying the position of the 
camera as represented by state->org. But what does it mean to modify state->org directly? 
Our intention by changing the z component of position in streak may have been to move the 
camera forward and backward in space. But what if the camera, through a transformation matrix 
defined in its instance block, had been pointing straight down? We might see something like 
Figure 24.17, maybe not what we would have expected from the previous renderings. 


camera "camera" 
output "rgba" "tif" "lens 5.tift" 
focal 1.5 


aperture 1 
aspect 1 
resolution 300 300 
environment = "sky" 
lens 
"streak" ( "max distance" .5 ) 


end camera 


instance "camera-instance" "camera" 
transform 


end instance 


Figure 24.17: Streaking the camera in z with the camera pointed straight down 


To be able make changes to position and direction that are relative to the camera itself, and not 
based on its position and orientation in space, we can transform state->org and state->dir to 
camera space. In that coordinate system, the camera is located at the origin and pointing down 
the negative z axis, with positive y straight up and the x axis parallel to the top and bottom edges 
of the projected image. The API library provides a number of coordinate space utilities; we'll be 
using functions that transform to and from camera space in our lens shaders. 


y axis 


viewing plane 


X=y=Z=0 -Z axis 


Figure 24.18: The result of transforming the camera to camera space, looking down the positive x axis 


Prog 190, 3.2. Coordinate 
Systems 
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Because we can create a consistent coordinate space for the camera no matter what transformation 
may be associated with its instance (and can transform back to the original space as well), we can 
readily specify eye ray modifications that are independent of camera direction. 


We’ll use the camera coordinate space to define a shader that simulates a wide-angle lens. At the 
most extreme angles, these are often called “fisheye” lenses. As a simple example, our shader 
won't be physically accurate, but can serve as a basis for other position-dependent modification 
of ray direction in a lens shader. 


First, we note that each ray is associated with a position in the viewing plane. 


Figure 24.19: Ray intersections in the viewing plane 


Given our transformed coordinate space, we can consider a new endpoint for the direction vector 
that would be created if we multiplied its z component by some value from 1.0 to 0.0. At 0.0, the 
vector would lie in the z=0 plane. 


Figure 24.20: Projecting the eye ray back toward the normal plane of the camera direction at its origin 


We can make the amount of z scaling for a ray dependent upon the distance from the center 
of the projected image on the view plane to that ray’s intersection point. Rays intersecting the 
viewing plane near the center of the image are only slightly modified in direction, while rays with 
intersection points at the edge of the image now lie in the z=0 plane. 
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Figure 24.21: Scaling the forward component of the eye ray based on distance from the image center 


We'll redraw these rays with the same length to better show how they now spread out from the 
eye position. Note that the simple calculation of scaling the z component results in an unequal 
angular difference between rays of equal distance in their intersection points. Different mappings 
from the viewing plane to ray angle can be used to define a variety of lens geometries. 


\ 


Figure 24.22: Normalizing the bent eye rays 


Each of these rays, though now pointed in a different direction, will still be used to calculate the 
value for the sample at the original intersection point in the viewing plane. 
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\ 


Figure 24.23: The association of the bent eye rays with the original intersection point in the viewing plane 


Now we'll implement this method to simulate a wide-angle lens, shader fisheye. Because we are 
basing our modification of an eye ray on the distance from its intersection point to the center of 
a circle, we will also need to handle rays that intersect points outside of this circle. Our fisheye 
shader includes a parameter to define the color that should be used for these outer rays. 


declare shader 
color "fisheye" ( 
color "outside color" default 111 ) 


apply lens 

scanline off 

trace on 
end declare 


Figure 24.24: Shader declaration of fisheye (p.575) 


The outside_color parameter surrounds the circular region of the fisheye image with white by 


default. 
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camera "Camera" 
Output “xoba” "tir" 
"lens 6.tili" 
focal 1.5 


aperture 1 


aspect 1 
resolution 300 300 
environment = "sky" 
lens 
"fisheye" () 
end camera 


Figure 24.25: Shader fisheye added as a lens shader in the camera 


As with streak, the most important part of the fisheye shader is the initiation of ray tracing 
with mi_trace_eye. 


struct fisheye { 
miColor outside color; 


miBoolean fisheye ( 
miColor *result, miState *state, struct fisheye *params ) 


miVector camera_direction; 
miScalar center _x = state->camera->x_resolution / 2.0; 
miScalar center y = state->camera->y resolution / 2.0; 
wiScalar radius = center _x < center _y 7? center_x : center y; 
miScalar distance from_center = 
miaux distance(center x, center _y, state->raster_x, state->raster_y) ; 


on 
OOWMWNHDUNFPWN EH 


ee 
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if (distance from_center < radius) { 

mi vector to camera(state, &camera_direction, &state->dir) ; 

camera direction.z *= miaux fit(distance from_center, 0, radius, 

mi vector normalize (&camera_direction) ; 

mi vector from_camera(state, &camera_direction, &camera_direction) ; 

return mi_trace eye(result, state, &state->org, &camera_direction) ; 
} else { 

*result = *mi_eval_color(&params->outside_color) ; 

return miTRUE; 
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Figure 24.26: Shader source of fisheye (p.575) 


In lines 9 and 10, we calculate the center of the rendered image in screen space in which [0,0] is the 
pixel in the lower left corner. In order for the distorted circular region to fit within the rendered 
image, the radius is chosen to be the smaller of the two center values in line 11. The current 
sampling point, the “projection point” of our diagrams, is [state->raster_x, state->raster_y], 


Rend 44, 3.8. Lenses: Depth 
of Field 
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so we use the center and current sample point coordinates to calculate the distance in image space 
in lines 12 and 13. 


If we are inside the radius (line 15), then we will bend the ray towards the camera’s z=0 plane 
based on the distance from the center in line 17, re-normalizing the manipulated vector in 
line 18. We convert the direction vector to and from camera space using library functions in 
lines 16 and 19. Finally, in line 20 the library function mi_trace_eye begins the tracing process 
with the original position of the camera, state->org, but with the modified direction vector, 
camera_direction. 


For any ray with a sample point outside the radius of line 11, the resulting color is set to the 
outside_color parameter value. Note that a lens shader can initiate the entire ray tracing process 
with mi_trace_eye but that this isn’t strictly necessary. A lens shader is free to calculate color 
values in any way. 


24.5 Depth of field 


Unlike a pinhole camera, a physical lens bends light rays through the refractive properties of glass 
so that only one plane at some distance from the lens is in true focus. 


focus 
double convex lens plane 
point 
in focus 
observed 
point 


Figure 24.27: Observed point at the focus plane in focus on the camera plane 


Areas in front of and behind this plane are out of focus in proportion to the distance from the 
focus plane and the size of the lens aperture that admits light into the camera. The apparent area 
that is in focus is called the depth of field. Light from a point that is beyond the focus plane will 
strike the back of the camera in an area called the circle of confusion. 
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double convex lens plane 
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Figure 24.28: Observed point beyond the focus plane 


Similarly, an observed point in front of the focus plane will create a similar circle of confusion on 
the viewing plane. 


focus 
double convex lens plane 
circle of 
confusion 
observed 
point 


Figure 24.29: Observed point in front of the focus plane 


In the previous two lens shaders, we manipulated the position and direction of the eye ray 

separately. In the following example, we’ll manipulate both position and direction. We’ll also 

use a strategy from the glossy reflection and refraction shaders and average a number of rays we 

generate from calls to the quasi-Monte Carlo sampling function, mi_sample. By combining the  Prog332, 3.26.3. Sampling 
result of a number of rays traced in a lens shader, we can simulate the blurry quality of depth of |— Yi"? ™-sample 


field. 


As in the fisheye shader, we’ll transform our rays into camera space and consider a single eye ray. 
The color of the projection point on the viewing plane is the result of tracing the eye ray. 
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y axis 


viewing plane 


eye ray 
projection point 


X=y=Z=0 -Z axis 


Figure 24.30: Defining a single eye ray in camera space 


In a physical camera, we can adjust a lens so that objects that are in a plane a certain distance from 
the camera appear to be in focus. For our depth of field shader, we’ll define a parameter called 
the focus_plane_distance for this. The intersection of the eye ray and the focus plane is the 
focus point, the one point along that ray for which objects will be in focus. 


We'll also define a parameter that will control how much objects at a given distance are blurred 
by the shader. The blur_radius defines a circular area around the original position of the camera 
in the z=0 plane of camera space. 


focus plane 


eye ray 
: focus point 
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Figure 24.31: Defining a radius around the camera in its normal plane and a focus point on a focus plane 


We can now consider the set of all rays that have as their origin a point in the circular area around 
the lens position and proceed through the focus point. In Figure 24.32, the gray region shows 
the location of all possible rays in that set. 
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focus plane 
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Figure 24.32: The cone (in gray) in which rays are traced and averaged to produce the depth of field image 


Our shader will simulate depth of field by tracing a number of rays in the gray region and 
averaging the result. Because every ray passes through the focus point, tracing those rays will 
all result in the same color for objects at the focus point. As objects become increasingly distant 
from the focus plane, the circular region in which traced rays calculate a color becomes larger 
and larger. The average of the resulting color from those rays therefore produces an increasingly 
blurry result. 


camera "Camera" 
output "rgba" "tif" "lens 7.tif" 
focal 1.5 
aperture 1 
aspect 1 
resolution 300 300 


environment = "sky" 
lens 


"depth, ef-field" ( 
"focus. plane distance" 9, 
"number of samples" 100, 
"lens radius" .2 ) 

end camera 


Figure 24.33: Lens shader depth_of field attached to the camera 


In the declaration of shader depth_of_field, we'll use the labels from the diagrams for the 
parameter names focus_plane_distance and blur_radius from the previous diagrams. We 
also define how many times we should call function mi_sample with the number_of_samples 
parameter. As with our glossy reflection and refraction shaders, the more samples we take, the 
better an approximation of depth of field our image will become. 
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declare shader 
color "depth of field" ( 
scalar "focus plane distance" default 1, 
scalar "blur radius" default .1, 


integer "number _of samples" default 1 ) 
apply lens 
scanline off 
trace on 
end declare 


Figure 24.34: Shader declaration of depth_of field (p.576) 


In the fisheye shader, we only needed to transform the direction vector, state->dir, to camera 
space. In simulating depth of field, we will also be transforming the position of the camera, 
state->org, to camera space. Since it is often useful to transform both position and direction to 
camera space, we'll define an auxiliary function, miaux_to_camera_space. 


void miaux_to camera_space ( 
miState *state, miVector *origin, miVector *direction) 


i 

2 

c 

4 mi point to _camera(state, origin, &state->org) ; 

= mi vector to camera(state, direction, &state->dir) ; 
6} 


Figure 24.35: Function miaux_to_camera_space 


Once we have finished our calculations in the camera space, we need to transform the position and 
direction vectors back to their original space before calling mi_trace_eye to initiate ray tracing. 
The auxiliary function miaux_from_camera_space inverts the effect of miaux_to_camera_space. 
Because the two functions are intended to be used as a pair, you would use as arguments to 
the second function the vectors initialized in the first, so the second function’s arguments are 
modified, rather than copied. 


void miaux_from_camera_space ( 
miState *state, miVector *origin, miVector *direction) 


mi vector from_camera(state, direction, direction) ; 


a F 
2 
3 
4 mi point from_camera(state, origin, origin) ; 
5 
6 


} 


Figure 24.36: Function miaux_from_camera_space 


Now we'll develop some utility functions to determine the modified origin of the eye ray and 
the position in the plane of focus toward which the eye ray points. 


We'd like to use the library function mi_sample to chose points around the original eye position 
for the circle of confusion. But since the results of mi_sample are distributed within the 
range [0.0,1.0), we'll redistribute them into a circle of a given radius by defining function 
miaux_square_to_circle. 
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void miaux_square to circle ( 


{ 


1 
2 
3 
4 float angle = M_ PI * 2 * x; 
5 
6 
7 
8 


float *result_x, float *result_y, float x, float y, float max_radius) 


float radius = max_radius * sqrt(y); 
*result_x = radius * cos(angle) ; 
*result_y = radius * sin(angle) ; 


} 


Figure 24.37: Function miaux_square_to_circle 


Now that we can remap points from a square to a circle, we’ll define a utility function called 
miaux_sample_point_within_radius to select new points more generally around an arbitrary 
point. We’ll use this function to find new eye ray origins within the circle of confusion around 
the original camera position. 


void miaux_sample point within _radius ( 
miVector *result, miVector *center, float x, float y, float max_radius) 
float x_offset, y offset; 


1 
2 
3 
4 
5 miaux_square to _circle(&x_offset, &y_offset, x, y, max_radius) ; 
6 result->x = center->x + x offset; 

r result->y = center->y + y_ offset; 

8 result->z = center->Z; 

9 


} 


Figure 24.38: Function miaux_sample_point_within_radius 


The focus point of the depth of field shader lies in a plane that is parallel to the camera’s z=0 plane 
and is focus_plane_distance away from the original eye ray’s origin along the z axis. Utility 
function miaux_z_plane_intersect finds the intersection of this plane and an arbitrary vector. 
In our shader, this vector will be the original eye direction. 


void miaux_z plane intersect ( 
miVector *result, miVector *origin, miVector *direction, miScalar z plane) 


miScalar z delta = (z plane - origin->z) / direction->z; 


result->y Origin->y + z delta * direction->y; 


af 
2 
3 
4 
5 result->x origin->x + z delta * direction->x; 
6 
7 result-s2, =.z.plane; 

8 


} 


Figure 24.39: Function miaux_z_plane_intersect 


Unlike shaders streak and fisheye, we'll call mi_trace_eye multiple times in an mi_sample Prog 332, 3.26.3. Sampling 
loop. The lens shader is free to do this; its only requirement is that it ultimately returns a color = Wi" ™-sample 
in its result argument. 
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struct depth_of field { 
miScalar focus plane distance; 
miScalar blur _ radius; 
miInteger number of samples; 


be 


miBoolean depth_of field ( 
miColor *result, miState *state, struct depth_of field *params ) 
{ 


2 
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miScalar focus plane distance = 

*mi_eval_ scalar (&params->focus_ plane distance) ; 
miScalar blur_radius = 

*mi_eval_ scalar (&params->blur_radius) ; 
miUint number of samples = 

*mi_eval_ integer (&params->number of samples) ; 


a 
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miVector camera_origin, camera_direction, origin, direction, focus point; 
double samples[2], focus_plane 2; 

int sample number = 0; 

miColor sum = {0,0,0,0}, single trace; 


a 
lO © 


miaux_ to camera _space(state, &camera_origin, &camera_direction) ; 


20 
wal 
ak 
23 


i) 
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focus plane z = state->org.z - focus_plane distance; 
Miaux Zz plane intersect ( 
&focus point, &camera_ origin, &camera_direction, focus plane 2); 


while (mi_sample(samples, &sample number, state, 2, &number_of_samples)) { 
miaux_sample point within_radius ( 
&origin, &camera_origin, samples[0], samples[1], blur_radius) ; 
mi vector sub(&direction, &focus point, &origin) ; 
mi vector normalize (&direction) ; 
miaux from _camera_space(state, &origin, &direction) ; 
mi_ trace eye(&single trace, state, &origin, &direction) ; 
miaux_add_color(&sum, &single trace) ; 
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} 


miaux divide color(result, &sum, number of samples) ; 
return miTRUE; 
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Figure 24.40: Shader source of depth_of field (p.576) 


We transform state->org and state->dir to camera space in line 22 to define camera_origin 
and camera_direction. In the mi_sample loop of lines 28-36, we use those transformed values 
to create the position and direction for each sample ray trace: lines 29-30 calculate the sample 
ray’s position, and then, given that position and the focus point from lines 24-25, its normalized 
direction in lines 31-32. The position and direction of this ray is then transformed back from 
camera space in line 33, and these modified values are used to trace a single ray in the mi_sample 
loop in line 34. The resulting color of each ray sent in the mi_sample loop is accumulated into 
sum in line 35. When the mi_sample loop has finished, the final result is calculated as the average 
of the accumulated color in line 37. 


24.6 Multiple lens shaders 


Like other shader types for materials, multiple lens shaders can be defined in the scene file in a 
list in the camera block. The syntax is the same as other shader lists. 


24.6 Multiple lens shaders 


camera "camera" 
OULpUuE "rgba" "tit" “lene 8.tirt" 
focal 1.5 


aperture 1 

aspect 1 

resolution 300 300 
environment = "sky" 


lens 
"depth of field" { 


"number of samples" 100, 
"lens radius" .2 ) 
"fisheye" () 
end camera 


Figure 24.41: Calling two lens shaders in a shader list in the camera block 
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"focus plane distance" 9, 


Unlike other shaders called in a list, however, lens shaders do not pass the result of their color 
calculation to the next shader in the result argument pointer. The order of execution is recursive; 
calling mi_trace_eye ina lens shader calls the next lens shader in the list if one exists. When the 
last lens shader is executed, the color result values are passed back up the sequence of recursive 
lens shader calls. The final rendering is therefore dependent upon the order of the lens shaders 


in the list. 


camera "camera" 
output "rgba" "tit" "lens 9.tif" 
focal 1.5 
aperture 1 
aspect 1 
resolution 300 300 
environment = "sky" 
lens 


"fisheye" () 

"depth of field" ( 
"focus plane distance” 9, 
"number of samples" 100, 
"lens radius" .2 ) 


end camera 


Figure 24.42: A different rendering produced by reordering the lens shaders 
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Chapter 25 


Rendering image components 


During the course of rendering, mental ray stores information in a set of predefined frame buffers. 
The typical output statement in the camera block writes color image data to a file on disk. You 
can define additional frame buffers for use in shaders, storing data in them and accessing that data 
in other shaders. 


25.1 Definition and use of frame buffers 


In most of the scenes we’ve rendered so far, we write out a single image file as the result of the 
rendering. The format and name of the file, as well as the type of data the file will contain, are 
defined as arguments to the output statement in the camera block. 


camera "cam" 
output "xrgba" "tit" "butier 1.ti£" 
focal 1.5 


aperture 1 

aspect 1.5 

resolution 300 200 
end camera 


Figure 25.1: A typical camera block in a scene file 


In Figure 25.1, the output statement creates a file called buffer_1.tif inthe tif file format. The 
rgba argument refers to one of the five standard frame buffers. The rgba frame buffer is always 
maintained by mental ray. Using one of the other four frame buffer types in an output statement 
is a signal to mental ray to create and maintain that frame buffer during rendering. 


Rend 293, 12.1. Image Types 


Prog 105, 2.7.2.1. Output 
Statements 


Prog 102, 2.7.1.11. Frame 
Buffer Control 


Prog 382, 3.26.12. Auxiliary 
Functions 


Prog 105, 2.7.2.1. Output 
Statements 
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tag 


Figure 25.2: The five standard frame buffers 
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Type 

Color 

Normals 
Depth 

Motion vectors 


Object labels 


Rendering image components 


You can also create any number of user frame buffers containing data of the five standard types, 
optionally writing that frame buffer’s data to file. Frame buffers are very useful in saving 
intermediate stages in the rendering process for later use in compositing or other post-rendering 


processes. 


User frame buffers are defined and used in three parts of the rendering process: 


1. Creation Frame buffers are created with the frame buffer statement in the options 


block and identified by the frame buffer index. 


2. Pixel access Two functions are available to get and put data into frame buffers: 
mi_fb_put(miState *state, int buffer_index, void *data_to_put) ; 
mi_fb_get(miState *state, int buffer_index, void *data_to_get) ; 


3. File output Frame buffers are written to disk with output statements in the camera block. 


Figure 25.3 depicts two user frame buffers, but additional frame buffers would be defined and 
accessed in the same way. The frame buffer index identifies the frame buffer in the options 
block and in the function calls in the shader. The index is preceded by “fb” in the camera block. 
Adding the “+” character to the beginning of the type causes mental ray to interpolate nearby 


values for pixels without any samples. 
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2. Get and put frame buffer pixels 


miBoolean shader ( 


{ 


micolor a, b; 


Dy eC); 
1, &d) ; 


mi fb put (state, 


options "opt" 

object space 
contrast mio ya” «3d: 43 
samples -1 2 


frame buffer 0 "+rgba" 
frame buffer 1 "+rgba" 


end options 


mi fb get (state, 


somo 
rome 


camera "cam" 


"FpboO" hee" 
‘Hutftexr 0 .tii" 


Sutpue "fbi" "tar" 
Prutiear t,he 
Outwut  “repat eae" 
"standard rgba.tift" 


Sutput 


1. Create frame buffers in memory 


end camera 


3. Write frame buffers to file 


Figure 25.3: Interaction of the scene file and shaders in the use of frame buffers 


25.2 Separating illumination components into frame buffers 


We'll modify the phong shader of Section 12.2.1 to write out its diffuse and specular components 
into separate frame buffers. The standard RGBA frame buffer will contain the combined 
rendering of the two components. 


declare shader 
color "phong framebuffer" ( 
color "ambient" default 
color "diffuse" default 


color "specular" default 
scalar "exponent" default 
array light "lights" ) 

end declare 


Figure 25.4: Shader declaration of phong_framebuffer (p.577) 


In Figure 25.5, the options and camera blocks include references to two user frame 


buffers. 
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options “opt" 
object space 
COOL rast. .«.1L-.si-.d-2 
samples -1 2 
frame buffer 0 "+rgba" 
frame buffer 1 "+rgba" 
end options 


camera "cam" 
buffer 2 diffuse.tif output "fbo" "tif" 
"puffer 2 diftfuse.tic" 
gqmctput “fthi" “Ear® 
"buffer 2 specular.tif£" 
output “"rgba" "tit" 
"SUSE 2.6L." 
crocal 1.5 
aperture 1 
aspect 1.5 
resolution 300 200 
end camera 


material "yellow" 
"phong framebuffer" ( 
"diffuse" 11 .5, 
"Specular" 111, 
"lights" ag ee ATO", "T,3"] 
end material 


buff 2 lar; t1 
urfer 2 specular; tit material: teed 


"phong framebuffer" ( 
'"dittrusge”™ 1 «5 «5; 
"Specular" 11 1, 
"lights" ee ae ad Or dae "E32" ] 
end material 


material "blue" 
"phong framebuffer" ( 
"ditfuge"™ .5°.5 i, 
"Specular" 11 1, 
"lights" [ "i , Ee” "TE3"] 
end material 


burter 2.tif 


Figure 25.5: Scene with standard RGBA output and two frame buffers 


With user frame buffers fb0 and fb1 created in the options block, shader phong_framebuffer 
can reference them by their indices, 0 and 1. 
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miBoolean phong framebuffer ( 
miColor *result, miState *state, struct phong framebuffer *params) 
{ 


miColor light color, diffuse_from_light, specular _from_light, 
diffuse component, specular_component ; 

int i, light count, light sample count; 

miVector direction toward light; 

miScalar dot_nl; 

miTag *light; 


miColor *diffuse = mi_eval_color(&params->diffuse) ; 
miColor *specular = mi_eval_ color(&params->specular) ; 
miScalar exponent = *mi_eval_scalar(&params->exponent) ; 
miaux light _array(&light, &light_count, state, 
&params->i light, &params->n_light, params->light) ; 


*result = *mi_eval_color(&params->ambient) ; 
miaux_ set channels (&diffuse_ component, 0.0); 
miaux_set channels(&specular_ component, 0.0); 


for (i = 0; i < light count; i++, light++) { 
miaux_set_channels(&diffuse from_light, 0.0); 
miaux_set_ channels (&specular_from_light, 0.0); 
light _sample_ count = 0; 


while (mi_sample light (&light_ color, &direction_toward_light, 
&dot nl, state, *light, &light_sample_ count) ) { 
miaux add diffuse component ( 
&diffuse from_light, dot _nl, diffuse, &light_color) ; 
miaux_add phong specular component ( 
&specular_ from_light, state, exponent, 
&direction toward light, specular, &light_color) ; 


} 


if (light sample count > 0) { 
miScalar scale factor = 1. 
miaux_add_scaled_ color ( 
&diffuse component, &diffuse from_light, scale factor) ; 
miaux_add_scaled_color ( 
&specular_ component, &specular_from_light, scale factor) ; 


0 / light sample count; 


} 
} 
mi fb put(state, 0, &diffuse_component) ; 


mi fb put(state, 1, &specular_component) ; 


miaux_add_color(result, &diffuse_ component) ; 
miaux_add_color(result, &specular_ component) ; 


return miTRUE; 


Figure 25.6: Source code of shader phong_framebuffer (p.577) 


The parameter struct for phong_framebuffer contains the same fields as the phong shader on 
which it is based. However, unlike phong, the diffuse and specular components of the illumination 
are not added together in the light loop, but accumulated separately. Lines 28-29 acquire the 
diffuse component of the current light in the light loop, adding that value to the accumulated 
diffuse component color in lines 37-38, scaled by light_sample_count, the number of samples 
taken of the light. Similarly, the specular component is acquired in lines 30-32 and accumulated 
in lines 39-40. The diffuse and specular values are put in the frame buffers with mi_fb_put in 
lines 43 and 44, respectively. It requires very little extra work to define the sum of the diffuse 
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and specular components in lines 46-47 to also create the output of the standard RGBA frame 
buffer. This image will provide useful feedback in a graphical interface for the appearance of the 
two components if they are composited together without modification. 


25.3. Compositing illumination components 


In the various illumination models in Chapter 12, the light loop always added the diffuse and 
specular components to accumulate the final result. We’ve split those two components into 
separate image files with a standard file format, so we can combine them in a separate image 
processing or compositing application. We can also manipulate these images before adding them, 
providing for an efficient way to make design changes without a potentially time-consuming 
repetition of the rendering process. 


Multiply RGB by 0.3 


Multiply RGB by 2.5 


Figure 25.7: Modifying the diffuse and specular components in a compositing operation 


Post-processing rendered image components can dramatically increase the flexibility of 
production pipelines. Other frame buffer data types can also provide input to post-processing 


25.4 Rendering shadows separately 427 


operations, such as the use of motion vectors in systems that create two-dimensional motion blur 
effects. 


25.4 Rendering shadows separately 


Creating separate compositing layers lets us defer some decisions until later in the production 
pipeline. We can also create a separate shadow pass layer in a shader. If we think of shadows 
as a scaling factor multiplied against the color that would be rendered if the shadows weren’t 
present, then we will want to define two frame buffer outputs for our shadow pass shader: the 
scene without shadows, and a shadow multiplier image. Multiplying these two images together 
will create the shadowed scene. 


How can we calculate the shadowing scaling factor? We need the ratio of the shadowed light 
to the unshadowed light which we can multiply against the unshadowed scene. We’ll define the 
utility function miaux_add_light_color that will sample a single light either with or without 
shadowing. 


void miaux_add_light_color ( 


{ 


miColor *result, miState *state, miTag light, char shadow_state) 


int light sample count = 0; 

miScalar dot_nl; 

miVector direction toward light; 

miColor sample color, single light color; 


const miOptions *original options = state->options; 
miOptions options copy = *original_ options; 

options copy.shadow = shadow state; 

state->options = &options copy; 


miaux_set_channels(&single light color, 0.0); 
while (mi_sample_ light (&sample color, &direction_toward_ light, 
&dot nl, state, light, &light sample count) ) 
miaux_add_ scaled color(&single light color, &sample color, dot_nl); 
1f (light sample count) 
miaux_add_scaled_color(result, &single light color, 
1.0/light sample count) ; 


state->options = (miOptions*) original options; 


Figure 25.8: Function miaux_add_light_color 


The values set in the options block in the scene file is also available in the miState struct. To  Prog213, 3.4.7. Options 
turn shadowing on and off, we’ll modify the shadow field of state->options. However, we 

need to make our own modified copy of the options structure in lines 9-12 and use it during 

our mi_sample_light loop in lines 15-17, restoring the original when we’re done in line 22. Our 

calculation of the color from a single light in lines 14-20, however, is the same as the body of a 

light loop in any of the illumination shaders. 


Now we’ll define shader shadowpass to create a separate shadow pass saved as a frame buffer. 
Parameter base_color is the color that will be attenuated by shadowing. 
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declare shader 
color "shadowpass" ( 


color "base _ color", 
array light "lights" ) 
end declare 


Figure 25.9: Shader declaration of shadowpass (p.579) 


The utility function miaux_add_light_color duplicates the inner loop from the illumination 
shaders; shader shadowpass wraps two calls to it in a loop over all the lights. 
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struct shadowpass { 


ee 


miColor base color; 
int i Light; 
int n Light; 
miTag light [1] ; 


miBoolean shadowpass ( 


{ 


miColor *result, miState *state, struct shadowpass *params ) 


int i, laght count; 
miTag *light; 
miColor without shadow, with shadow, shadow; 
miColor *base color = mi_eval_color(&params->base_ color) ; 
miaux light array(&light, &light count, state, 
&params->i light, &params->n_light, params->light) ; 


miaux_ set channels (&without_ shadow, 0.0); 
miaux_set_channels(&with_ shadow, 0.0); 


for (i = 0; i < light count; i++, light++) { 
miaux_add_ light color (&without_ shadow, state, *light, miFALSE) ; 
miaux_add light color(&with shadow, state, *light, miTRUE) ; 


} 


miaux divide colors(&shadow, &with_ shadow, &without_shadow) ; 
miaux_ multiply colors(result, base color, &shadow) ; 

mi fb put(state, 0, base _ color); 

mi fb put(state, 1, &shadow) ; 


return miTRUE; 


Figure 25.10: Shader source of shadowpass (p.579) 


In lines 21-24, the light colors with and without shadowing are accumulated in separate variables. 
When we’ve looped through all the lights, the ratio of the shadowed to unshadowed values 
calculated in line 25 gives us the scaling factor to create the shadowed result of our input color in 
line 27. The first frame buffer stores that unshadowed input in line 28, the second frame buffer 
stores the shadow scaling image in line 29. As with the phong_framebuffer shader, the standard 
RGBA frame buffer contains the default combination of the two frame buffer components 
calculated in line 27. 


The base_color parameter of shadowpass can be the result of a shader. In Figure 25.11, we use 
the phong shader to create the shader definitions phong_yellow, phong_red, and phong_blue as 
input to the base_color parameter to shadowpass. 
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options "opt" 
object space 
contrast ).05! .05:.05 1 
samples -l 2 
shadow off 
frame buffer 0 "+rgba" 
frame buffer 1 "+rgba" 
end options 


camera "cam" 
Sueput ‘"ibo"."Gak" 
"buffer 3 without_shadows.tif" 
CUtnUE "EDI" “tirt* 
"buffer 3 shadows.tif" 
output: "rgba™! “car 
Yhutlar | 3.tar" 
focal 1.5 
buffer _3 without shadows.tif aperture 1 
aspect 1.5 
resolution 300 200 
end camera 


shader "yellow _phong" 
*“pnong™ ( 
"diffuse" 11 .5, 
"Specular" 111, 
PLightse” PTET" , "T,2 a "7,3 ny] 


shader "red phong" 
"phong" ( 
"ditfuse”™ 1..5 .5, 
‘SoecuLar’ “i'r 1, 
"lights" [Pi ™ , a "T3"] ) 


shader "blue phong" 
"phong™ ( 
"diffuse" .5 .5 1, 
"Specular" 111, 
"lights" iene wT ae "7,3 "| ) 


buffer 3 shadows.tif 


material "yellow" 
"Shadowpass" ( 
"base color" = "yellow_phong", 
"lights" "LL", vue", "T,3"] ) 
end material 


material "red" 
"Shadowpass" ( 
"base color" = "red phong”, 
flights" ["L1 : "EQ", "T,3"] ) 
end material 


material "blue" 

"Shadowpass" ( 

butter. 3 .tif "base color" = "blue _phong", 
"lights" ["L1i", "TQ", "T3"] ) 

end material 


Figure 25.11: Separating shadows into a separate frame buffer 


Prog 382, 3.26.12. Auxiliary 
Functions 
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25.5 Saving components from standard shaders 


To create image files from the diffuse and specular components in the phong shader we created a 
new shader that calculated those components separately. Relative to the work required in phong 
to calculate the light color and direction in the light loop, the addition of frame buffers didn’t 
increase the rendering time much at all. However, we had to rewrite the phong shader to do it. 
If we are willing to spend some extra time in rendering, at least in the exploratory phase of a 
project, we can generate image component frame buffers from many standard shaders. We'll use 
the original phong shader in a Phenomenon along with some other component shaders for the 
Phenomenon graph to duplicate the multiple output images of phong_framebuffer. 


First, we'll separate writing frame buffer data into a component shader, framebuffer_put. It 
takes as parameters the color to write to the frame buffer and the frame buffer index. 


declare shader 
color "framebuffer_ put" ( 
color "coloer’, 
integer "index" ) 
end declare 


Figure 25.12: Shader declaration of framebuffer_put (p.580) 


Shader framebuffer_put does no color calculations of its own, but merely passes its color 
through as its result. In the Phenomenon graph, we will use the diffuse and specular outputs 
from two separate calls to the phong shader as inputs to two calls to framebuffer_put. 


struct framebuffer put { 
miColor color; 
miInteger index; 


}; 


miBoolean framebuffer put ( 
miColor *result, miState *state, struct framebuffer put *params) 
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{ 
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*result = *mi_eval_ color (&params->color) ; 


= 
co 


if (state->type == miRAY_ EYE) 
mi_fb put(state, *mi_eval_integer(&params->index), result) ; 
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return miTRUE; 


a 
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Figure 25.13: Shader source of framebuffer_put (p.580) 


We are only concerned with the result of the primary ray, so in line 11 we check the ray type. 
The index parameter, used as the second argument to mi_fb_put in line 12, allows us to write to 
any frame buffer defined in the scene file options statement. 


Now that we have the illumination components, we need to add them together. We’ll add the 
diffuse and specular values from the two calls to framebuffer_put in shader add_colors. 
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declare shader 
color "add eolers™ : ( 


GoLor ola": 
eolexr ys") 
end declare 


Figure 25.14: Shader declaration of add_colors (p.580) 


Adding two colors is simply the result of adding the colors’ corresponding channels to create a 
new color. 


struct add_colors { 
miColor x; 
miColor y; 


}3 


miBoolean add colors ( 
miColor *result, miState *state, struct add_colors *params) 
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miColor *x = mi_eval_ color (&params->x) ; 
miColor *y = mi_eval_ color (&params->y) ; 


result->r = X->r + y->©r; 
result->g X->9 + Y->gG; 
result->b = x->b + y->b; 
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return miTRUE; 
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Figure 25.15: Shader source of add_colors (p.580) 


Now that we can put data in frame buffers and add colors together in separate shaders, we can 
design a Phenomenon graph to duplicate phong_framebuffer using the original phong shader. 
We'll call the Phenomenon phong_components. 


phong_ components 


= 


diffuse 


specular 
exponent 


phong 
specular 0 0 0 
exponent 0 


framebuffer put 
index 0 


add_colors 


phong 
ambient 0 0 0 
diffuse 0 0 0 


framebuffer put 
index 1 


Figure 25.16: Design of a Phenomenon to calculate components by using shader phong twice 


The input parameters for phong_components are identical to phong and phong_framebuffer so 
that we will be able to use it in the same scene as before. To create the diffuse component, we 
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set the specular parameter to black rather than passing the value of the Phenomenon interface 
parameter. Conversely, to create the specular component, we set the diffuse and ambient 
parameters to black. These two components are then passed to framebuffer_put to output 
their values to the frame buffers identified by the indices specified as parameter values. Finally, 
the color values that have been passed through the framebuffer_put calls are added together in 
add_colors as the output value of the Phenomenon. 


Figure 25.17 is the implementation of Figure 25.16 as a Phenomenon. 


declare phenomenon 
color "phong_ components" ( 
color "ambient" default 
color "diffuse" default 
color "specular" default 
scalar "exponent" default 
array light "lights" ) 


shader "diffuse component" 
W phong W ( 
"ambient" = interface "ambient", 
"diffuse" interface "diffuse", 
"Specular" 0 0, 
"exponent" OQ, 
"lights" interface "lights" ) 


shader "specular component" 
" phong " ( 
"ambient" 0 0 0, 
"diffuse" 000, 
"Specular" = interface "specular", 
"exponent" = interface "exponent", 
"lights" = interface "lights" ) 


shader "fb diffuse" 
"framebuffer put" ( 
"color" = "diffuse_component", 
"index" 0 ) 


shader "fb specular" 
"framebuffer put" ( 
"color" = "specular component", 
"index" 1 ) 


shader "add components" 
"add _ colors" ( 
"x" = "fb diffuse", 
"y" = "fb specular" ) 


root = "add components" 


end declare 


Figure 25.17: A reimplementation of shader phong_framebuffer as a Phenomenon 


You can see in Figure 25.17 that shader phong is called twice in the Phenomenon graph, but with 
black (zero) values for parameters that effectively separate the combined diffuse and ambient 
components from the specular component. 


The use of the phong_components Phenomenon in Figure 25.11 is syntactically identical to the 
corresponding use of shader phong_framebuffer in Figure 25.5. 
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options "opt" 
object space 
Sonerast: 21 .1 .L tt 
samples 2 2 
frame buffer 0 "+rgba" 
frame buffer 1 "+rgba" 
end options 


camera "cam" 
buffer 4 diffuse.tif output, "fbo" "tit" 
"buffer 4 diffuse.tif" 
Butput "Ebi". "cit? 
"puffer 4 specular.tif" 
SuUtput “rapa” "ti" 
"butter 4.tii" 
rocai 2.5 
aperture 1 
pepect 1.5 
resolution 300 200 
end camera 


material "yellow" 
"phong components" ( 
"diffuse" 11 .5, 
"Specular" 2 2 2, 
"lights" Gerke pl "T3"] 
end material 


buff 4 ok 
ulfrer 4 specular.tif material "red 


"phong_ components" ( 
"ditfuse" 1 .5 .5, 
"Specular" 2 2 2, 
"lights" [Vi ; "ia", "7,3 ny 
end material 


material "blue" 
"phong components" ( 
"diffuse" .5 .5 1, 
"specular" 22 2, 
tights” ["L1", "TQ", "T.3"] 
end material 


Durrer 4.tif 


Figure 25.18: Using the phong_components Phenomenon to create frame buffer image files 


With the phong_components Phenomenon we were able to create frame buffer images from a 
shader that was not originally designed to do so. The development of similar Phenomena can 
take place early in a project to explore the possibilities of frame buffers in a production pipeline. 
If the initial research is promising, you can then begin the additional work of writing custom 
shaders with a proof of concept in hand. 
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25.6 Using a material Phenomenon with framebuffer components 


Adding a frame buffer that stores the indirect illumination component is a direct extension of the 


Phenomenon in Figure 25.17. 


declare phenomenon 


Figure 25.19: A Phenomenon with frame buffers containing the diffuse, specular and indirect components 


"global phong_ components" ( 
color "diffuse" detauts .5 .5-..5, 
color. "specular® detagle ss <3 <3; 
scalar "exponent" default 30, 
array laght:. "Lignte”™-} 


shader "diffuse" 
"phong WW ( 
"diffuse" = interface "diffuse", 
"lights" = interface "lights", 
"Specular" 0 0 0 ) 


shader "specular" 
" phong " ( 
"Specular" = interface "specular", 
"exponent" = interface "exponent", 
"lights" = interface "lights", 
“diffuge" Ooh G } 


shader "indirect" 
"average radiance" () 


shader "indirect diffuse" 
"op mul_cc" ( 
"AY = "“indirect®, 
"B" = interface "diffuse" ) 


shader "write diffuse" 
"framebuifer_ pul. 


"color" = "diffuse", 
"index" 0 ) 


shader "write specular" 
"framebuffer put" ( 
"color" = "specular, 
"index" 1 ) 


shader "write indirect" 
"framebuffer put" ( 
"color" = "indirect diffuse", 
"index" 2 ) 


shader "add direct" 
"add _ colors" ( 
"x" = "write diffuse", 
"y" = "write specular" ) 


shader "add _ indirect" 
"add _ colors" ( 
vx" = "add direct", 
Hy" = “write indirect." ) 


root = "add indirect" 


end declare 
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The shader average_radiance from page 225 used in the indirect graph node calculates the 
indirect illumination component. Because this value represents incoming indirect illumination, 
it is multiplied by the diffuse color in shader indirect_diffuse. Shader graph nodes 
write_diffuse, write_specular, and write_indirect store the components in frame buffers 
using shader framebuffer_put. By using shader add_direct twice we can add the diftuse, 
specular and indirect components together. 


But rendering indirect illumination also requires that a material include a photon shader so that 
the surface will record the photons’ interactions with it. A material Phenomenon, as described 
on page 45, can include photon shaders. Since a typical photon shader may use the same diffuse 
color as the corresponding material shader, we can define a material Phenomenon in which the 
interface parameter for the diffuse color is used in both shaders. 


declare phenomenon 
material "global _phong" ( 
color "diffuse" default 1:11, 
array light "lights" .) 


material "phong buffers" 
"global _phong_components" ( 
"diffuse" = interface "diffuse" 
"Specular" 14141, 
"lights" = interface "lights" ) 
photon 
"store diffuse photon" ( 
"diffuse color" = interface "diffuse" ) 
end material 


root material "phong buffers" 
end declare 


Figure 25.20: A material Phenomenon including a photon shader sharing the diffuse color parameter 


Phenomenon global_phong is a general way of combining framebuffer output with the photon 
shader required for indirect illumination. However, we can also think of Phenomena as a 
convenient way of defining shader combinations that are specific to a scene. For example, we’ve 
generalized light instance input to global_phong by defining an array of lights as an interface 
parameter called lights. If we always want to use the same light instance in our Phenomenon 
for a specific scene, we can remove the interface parameter, and instead embed a reference to the 
light instance in our shader graph. 
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Llignt “Light® 
‘spotlignt® { 
"Ligne.color™ 
origin 4 -.5 7 
direction -4 .5 -7 
spread .9 
end light 


instance "light inst" "light" end instance 


declare phenomenon 
material "global phong with light" ( 
color "diffuse" default 111 ) 


material "phong buffers" 
"global _phong_ components" ( 
"diffuse" = interface "diffuse", 
"Specular" 1141, 
"lagnte™ { ":tlighte amet” |.) 
photon 
"store diffuse photon" ( 
"diffuse color" = interface "diffuse" ) 
end material 


root material "phong buffers" 
end declare 


Figure 25.21: A material Phenomenon that includes a photon shader and a light instance reference 


Phenomenon global_phong_with_light does not have a parameter for the lights to be used in 
calculating the direct illumination. Instead, the light instance that is defined in the global scope ot 
the scene can be identified as a shader parameter by preceding its name with two colon characters 
(::). Without the prefix, the identifier light_inst refers to elements within the Phenomenon’s 
namespace. Using the :: prefix redefines the light_inst symbol to be found in the namespace 
of the scene itself. 


In Figure 25.22, the separate material used for each object is defined by the shader definitions 
created by the global_phong_with_light Phenomenon. A material Phenomenon used in this 
way can be thought of as a procedure that produces specific materials from a generalized 


design. 
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options "opt" 
object space 
Contrast «lL ch eka 
samples 0 2 
finalgather on 
finalgather accuracy 50 2 .5 
frame buffer 0 "+rgba" 
frame buffer 1 "+rgba" 
frame buffer 2 "+rgba" 
end options 


shader "red" 
butter. 5 diffuse. tat "global _phong with light" 
"diffuse" 1 .4 .4 ) 


shader "yellow" 
"global _phong with light" 
"diffuse" .8 .7 .4 ) 


Shader "blue" 
"global phong with_light" 
"diffuse" .4 .41 ) 


shader "darkgray" 
"global _phong_with_light" 
"diffuse" .1 .1 .1 ) 


shader "white" 
butter 5 specular .tit "global phong with light" 
"diffuse" 111 ) 


camera "cam" 
Sutput Eo0" “tac” 
"buffer 5 diftfuse.tar" 
eucput "fbi" “cir 
"DBUrfer 5 specular.tit" 
eutput "tb2z" “tit" 
‘putter 5 indarect,tii® 
OULPUE "Taba" "tit" 
"buffer 5.tit" 
focal 90 
aperture 33.3 
aspect 1.4 
resolution 420 300 
mMircer 5 iat rect,.tiz environment 
"one color" ( 
"eoler" «J. «ol «2 ) 


end camera 


instance "square-1" 
geometry "bw square" ( 
"name" "bw-square" ) 
material "darkgray" 
transform 
0.1 0 0 
0 0.1 0 
oO 2 @.4 
0 0 O:2 
3 


globillum 
end instance 


buffer 5.tit 


Figure 25.22: Using a material Phenomenon to save the indirect illumination component 
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Creating a definition of a material Phenomenon looks just like a shader call. However, the shader 
definition that the material Phenomenon creates can be used in the scene in the same way as an 
actual material. In Figure 25.22, the object instance square-1 uses as its material the darkgray 
shader definition. The other shader definitions, red, yellow, blue, and white, are used in the 
same manner for the materials of the other objects in the scene. 


The global_phong_with_light material Phenomenon simplifies the assignment of a complex 
set of shaders and their parameters to a number of objects in the scene. Such flexibility in the 
use of Phenomena can be very helpful in the design and development stages of a project. Later, 
when standard procedures are defined for artists for the production phase, the original structures 
employed during development can be reorganized easily to fit production requirements. 


Chapter 26 


Modifying the final image 


All of our scenes have saved the result of rendering to a file on disk with an output statement Prog 105, 2.7.2.1. Output 

in the camera block. This was also the mechanism we used to write out frame buffer data in the meee 

previous chapter. Writing files is a special case of output shaders, a process that executes after the Prog35, 1.29. Output Shaders 
samples have been filtered to create pixels. 


You can also use output shaders as one last opportunity to modify the rendered image. Rather Prog 279, 3.19. Output 
than dealing with rays traveling through geometric space, output shaders provide access to the pats 
image’s pixel data, as well as the other data stored in frame buffers during rendering. Output 

shaders can implement a final image processing pass over the rendered image. 


26.1 An image processing vocabulary 


Most image processing systems provide at a minimum a way to open and close an image data 
structure and a way to acquire data from and assign data to individual pixels. In an output shader, 
you can use API library functions to perform these four basic image processing activities. The Prog 343, 3.26.6. IMG 


mental ray struct milmg_image provides access to the data in frame buffers. Pixel access function ieioaii 
names are based on the type of data contained in the frame buffer. 

Action Function 

Open milimg_image *mi_output_image_open(miState *state, miUint index) 

Close void mi_output_image_close(miState *state, miUint index) 

Get void mi_img_get_type-name(miImg_image *image, get-type value, int x, int y) 

Put void mi_img_put_type-name(milImg_-image *image, put-type value, int x, int y) 


Figure 26.1: Library functions useful in output shaders 


The x and y integer coordinate values are oriented with [0,0] in the lower left corner of the image. 
The index argument is one of the predefined constants that identifies the frame buffer. 
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Index name Framebuffer description Typename “Get”type “Put” type 
miRC_IMAGE_RGBA RGBA color color miColor* miColor* 
miRC_IMAGE_Z Depth scalar float* float 
miRC_IMAGE_N Normal vector normal miVector* miVector* 
miRC_IMAGE_M Motion vector vector miVector* miVector* 
miRC_IMAGE_TAG Object label label miUint* miUint 
miRC_IMAGE_COVERAGE Coverage coverage float* float 
miRC_IMAGE_USER First user-defined (fb0) (as defined) (as defined) 


Figure 26.2: Output image identification constants 


The shaders in this chapter will manipulate color data in the frame buffers, so we’ll be using 
pixel access functions mi_img_get_color and mi_img_put_color for pixel data of type miColor. 
A typical structure for a color output shader that modifies the original contents of the RGBA 
frame buffer loops over all the pixels in all the scanlines. 


open the image data structure 
for y in each row 
for x in each column 
get the value of pixel [x,y] 
modify the pixel value 
put the modified value in [x,y] 
close the image data structure 


Figure 26.3: Pseudocode description of a typical output shader for manipulating color 


You may recognize the pseudocode of Figure 26.3 as a basic structure for an image processing 
routine. The color data available in the output shader is still in floating point format; depending 
upon the design of the production pipeline, certain image processing functions might be more 
accurately calculated at this point. 


26.2 Adding a letterbox mask 


Like the frame buffer output statements in the last chapter, output shaders are added to the 
camera block. We’ll add output shaders to this scene. 
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camera "cam" 
eutpout. "reba". "hit" 
'Sucput 1.12" 
focal 1.5 


aperture 1 

aspect 1.333 

resolution 400 300 
end camera 


Figure 26.4: Camera with standard file output and no output shaders 


Our first output shader, letterbox, will darken the top and bottom of the frame to indicate an 
image area of a different aspect ratio than the full frame. 


declare shader 
eolor "letterbox" ( 
scalar "aspect_ratio" default 1.85, 
color "outside scale" default 000 ) 
end declare 


Figure 26.5: Shader declaration of letterbox (p.581) 


By default, the shader will create the letterbox margins at an aspect ratio of 1.85 (“matted 
widescreen”) with black for the matted area. 


camera "cam" 
SutEput "reba" 
"letterbox" () 
SCutput "raba", "tir" 
'SurpUL 2.CiE" 


focal 1.5 

aperture 1 

aspect..1.333 

resolution 400 300 
end camera 


Figure 26.6: Camera with output shader letterbox added 


The letterbox shader follows the structure of Figure 26.3, opening the miImg_image structure, 
reading and writing pixel data, and closing the image when done. 
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struct letterbox { 
miScalar aspect ratio; 
miColor outside scale; 


bi 


miBoolean letterbox ( 
void *result, miState *state, struct letterbox *params) 


int x, ¥; 

miColor pixel; 

miScalar aspect_ratio = *mi_eval_ scalar(&params->aspect_ratio) ; 
miColor *outside_ scale = mi_eval_color(&params->outside scale) ; 
miScalar image width = state->camera->x_resolution; 

miScalar image height = state->camera->y resolution; 

miScalar letterbox height = image width / aspect ratio; 
miScalar y min = (image height - letterbox_height) / 2.0; 
miScalar y max = image height - y min; 
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miImg image *fb = mi_output_image open(state, miRC_IMAGE RGBA) ; 


for = 0; y < state->camera->y resolution; y++) { 
if (mi_par_aborted() ) 
break; 
for (x = 0; x < state->camera->x resolution; x++) { 
mi_img get _color(fb, &pixel, x, y); 
if (y < ymin || y > y_max) { 
miaux multiply colors(&pixel, &pixel, outside scale) ; 
mi_img put _color(fb, &pixel, x, y); 
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mi output _image_ close(state, miRC_IMAGE RGBA) ; 


return miTRUE; 
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Figure 26.7: Shader source of letterbox (p.581) 


An output shader may take much longer to execute than other shaders since it could process data 
for all the pixels of a large image. To give mental ray the opportunity to handle an abort issued 
by the user, the function mi_par_aborted on line 22 checks the current status of pending signals. 
Here we’re checking at every scanline. This particular shader executes so quickly that this check 
for aborts is hardly necessary, but it’s good practice in general to allow for output shaders to 
handle aborts. 


The “get” and “put” operations are in the inner loop in lines 25 and 28, respectively. If the 
condition in line 26 is satisfied, we’re outside the area of the desired aspect ratio, so we scale the 
color by the outside_scale parameter. Notice that mi_img_put_color is part of the conditional; 
we're leaving the pixel colors alone if we’re inside the letterbox. 


In line 32 we finish the processing of the color frame buffer with mi_output_image_close. 
Rather than passing the image variable, which would be typical for such a function in an image- 
processing context, we use the same framebuffer index identifier as we did to open the image, 
miRC_IMAGE_RGBA. 


The color change of the letterbox margin is parameterized with the scaling factor outside_scale. 
For some animation tests at an early stage of production, it can be useful to see where moving 
objects are located in the frame with respect to the area that will actually be projected. 
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camera "cam" 
output "rgba" 
"letterbox" ( 
Yappect ratio". 2.55, 
"Outside scale" .4 .4 .4 ) 


eutput "rsagba" "tit" "“eutput 3.t10" 
rogal iS 
aperture 1 
aepect 1.333 
resolution 400 300 
end camera 


Figure 26.8: Camera with letterbox output shader with the Cinemascope aspect ratio of 2.55 


26.3 A median filter in a shader 


The letterbox shader only multiplied individual pixels by a scaling factor to darken part of the 
standard RGBA frame buffer. Many classical image processing operations modify a given pixel 
based on the pixel neighborhood, the region of pixels within a given “radius” around that pixel. 
Blurring is a typical example of this kind of process, with a pixel’s neighborhood averaged in 
some way to create a new value for the central pixel. 


radius = 1 


radius =2 


radius = 3 


Figure 26.9: A radius defining a square region of pixels around a central pixel 


A median filter defines a new pixel value by collecting each neighborhood of pixels into a list, 
sorting the list based on color value, and replacing the original central pixel with the pixel in the 
middle of the sorted list. A typical application of the median filter is the removal of incorrect 
pixels in “noisy” images, replacing those noisy pixels with another, possibly more accurate, pixel 
in the neighborhood. For rendered images, the median filter can create interesting effects because 
of the way in which it appears to blur the image, but preserves detail. 


We’ll define an output shader that will perform a median filter on the rendered image. Its only 
parameter will be the radius for the size of the pixel neighborhood. 
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declare shader 
color "median filter" ( 


integer "radius" default 1 ) 
end declare 


Figure 26.10: Shader declaration of median_filter (p.582) 


Collecting the pixel values in a neighborhood can be useful for a number of image processing op- 
erations, so we'll define an auxiliary function for that step, miaux_pixel_neighborhood. 


void miaux_pixel_ neighborhood ( 
miColor *neighbors, 
miImg image *buffer, int x, int y, int radius) 


int Bi, Va, xp. =. 0,. vo = 0, 4.5.9, 
max x = buffer->width - 1, max_y = buffer->height - 1; 
miColor current_pixel; 
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\O 


for (yi = y - radius; yi <= y + radius; yi++) { 
yp = yi > max_y ? max_x : yi < 0? 0: yi; 
for (xi = x - radius; xi <= x + radius; xi++) { 
xp = XL > Max. x 7 Max_=E.< Xi <0 7.0 2 Biz 
mi img get _color(buffer, &current_pixel, xp, yp); 
neighbors [i++] = current _pixel; 
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Figure 26.11: Function miaux_pixel_neighborhood 


We assume in miaux_pixel_neighborhood that the memory pointed to by argument neighbors 
has already been allocated in the calling function. The variables xi and yi in the for loop 
statements in lines 9 and 11 iterate through the pixel coordinates within the radius. Pixels on 
the border of the image won’t have a full set of neighborhood pixels, so in lines 10 and 12 we 
keep the pixel coordinate within range. Repeating border pixels for the median filter’s sort step 
preserves the property of removing noisy pixels. (Other image processing operations may want 
to “wrap around” to use pixels from the other side of the image or substitute some default pixel 
value instead.) 


To sort the pixels in the neighborhood, we’ll use the standard C function qsort. One of its 
arguments is the function that compares two values to decide if they are less than, equal to, or 
greater than each other. We’ll define a comparison of two colors to be the numerical comparison 
of the sum of their red, green and blue channels. 


int miaux_color_ compare(const void *vx, const void *vy) 


{ 


miColor const *x = vx, *y VY; 


float sum_xX = X->r + X->g x->b; 
float sum_y = y->r + y->g y->b; 
recurn 8um, x < sum_y ? -1 +: Sums > sumy ¥ is. OF; 


Figure 26.12: Function miaux_color_compare 
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The function signature for the qsort comparison function has two pointers to void for its 
arguments, so in line 3 we cast these values to miColor and sum their channels in lines 4 and 5 for 
the values to use in the comparison. The return value for the qsort comparison function returns 
three different values based on the sort order of its arguments, calculated in line 6. 


Condition Return value 


A<B Less than 0 
A=B 0 
A>B Greater than 0 


Figure 26.13: Return values for a standard comparison function used in sorting 


With these auxiliary functions in hand, the structure of the median_filter shader is clearly 
based on the iteration through the pixel values of the RGBA frame buffer. However, because the 
median filter technique depends upon neighboring pixels in its calculation, we can’t change those 
values in place as we did in the letterbox shader. 


struct median filter { 
miInteger radius; 


miBoolean median filter ( 
void *result, miState *state, struct median filter *params) 


ONAN UF WDND BP 


miColor *neighbors; 

int radius = *mi_eval_ integer(&params->radius), x, y, 
kernel size = (radius * Qeted). * ofBadius.*» Qotoddy 
middle = kernel size / 2; 


\O 
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miImg_image *fb input = mi_output_image open(state, miRC_IMAGE RGBA) ; 
miImg_ image *fb output = mi_output_image open(state, miRC_IMAGE USER) ; 


HH 
U1 


neighbors = (miColor*) mi_mem_allocate(kernel size * sizeof (miColor) ) ; 
for (y = 0; y < state->camera->y resolution; y++) { 
if (mi_par_aborted() ) 
break; 
for (x = 0; x < state->camera->x_ resolution; x++) { 
miaux_ pixel neighborhood(neighbors, fb input, x, y, radius) ; 
qsort (neighbors, kernel sizé, sizeof (miColor) , 
miaux_ color compare) ; 
mi_img put _color(fb output, &neighbors [middle], x, y); 
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} 
} 


mi_mem_release (neighbors) ; 
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mi_output_image _close(state, miRC_IMAGE RGBA) ; 
mi _output_image_close(state, miRC_ IMAGE USER) ; 


return miTRUE; 
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Figure 26.14: Shader source of median_filter (p.582) 


One of the frame buffer index constants, miRC_IMAGE_USER, is the index of the first user frame 
buffer from the previous chapter. Other user frame buffers are accessed by adding the index 
number to this constant, so the second frame buffer would be miRC_IMAGE_USER+1. We'll put the 
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result of the median value calculation into the first user frame buffer, which we open in line 14 
and into which we put a pixel value in line 24. The neighbors pixel array, allocated in line 16, is 
filled with the pixel neighborhood in line 21 and sorted in lines 22-23. The comparison function 
miaux_color_compare is used as the fourth argument to qsort in line 23. Since the neighbors 
array is sorted, the pixel at neighbors [middle] is the median value which is put into the first 
user frame buffer in line 24. 


Any memory allocated with mi_mem_allocate should be released with mi_mem_release, so we 
free the neighbors array in line 27. We also close the two frame buffer image pointers in 
lines 29 and 30. 


options "opt" 
object space 
samples 0 2 
SCONCYaASE «i «1 «ad J 
trace depth 2 2 4 
frame buffer 0 "+rgba" 
end options 


output 4.tif camera "cam" 
- output "rgba”" 


"median Filter" ( 
"radius" 4 ) 
output "rgba" "tif" 
VoutpuL.4.b25" 
OuEpue. "Lbo". "cri" 
"Output _4 median.tif" 
focal, 1.3 


aperture 1 

aspect 1.332 

resolution 400 300 
end camera 


output_4 median.tif 


Figure 26.15: Using the first user frame buffer as the output of an image processing operation 


In the scene file of Figure 26.15, we have to be sure to define frame buffer 0 in the options block 
and write it out to file in the camera block. This preserves the original image, allowing it to be 
written to file along with the filter image. However, the user of median_filter must know that 
it requires frame buffer 0. If keeping the original image is not required, the user frame buffer 


could be copied to the RGBA frame buffer after all pixels have been processed. 
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void miaux_copy frame buffer ( 


{ 


miImg image *source, miImg_ image *destination) 


4. 
2 
3 
4 IBS K, Pes 

5 miColor pixel; 

6 for (y = 0; y < source->sheight; y++) 

7 for (x = 0; x < source->width; x++) { 

8 mi img get _color(source, &pixel, x, y); 

9 mi_img put _color(destination, &pixel, x, y); 
10 
“fal 


} 


Figure 26.16: Function miaux_copy_frame_buffer 


26.4 Compositing text over a rendered image 


Developing shaders is an experimental science and art, and keeping track of the details as you 
work on new techniques can be difficult. Shader annotate will composite text over a rendered 
image. This can be very useful for including the frame number or the date in a test rendering, or 
listing the varying parameter values in a series of test images. 


camera "cam" 
output "“reoba" 
"annotate" ( 
"fontimage filename" 
"Courier-Bold 24.fontimage", 
"text" "Frame 42" ) 
Seutput “raba"” "rit 
Lourtpul, S.tiet* 
Focal S06 
aperture 335.3 
aspect 1.5 
resolution 400 300 
end camera 


Frame 42 


Figure 26.17: Adding text to an image using the annotate output shader in the camera 


Shader annotate s ecifles the text to be com osited in the ima C, its color, and osition as 
p Pp 5 Pp 
parameters. 


declare shader 
color "annotate" ( 
string "text", 
string "fontimage filename", 


integer "x" default 10, 

integer "y" default 10, 

color "color" default 111 ) 
end declare 


Figure 26.18: Shader declaration of annotate (p.583) 


To make the definition of the characters of the text as portable as possible, shader annotate uses 
its own idiosyncratic format for a text font, called a fontimage. (Appendix C on page 609 contains 
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an example program that creates a fontimage file.) The basic principle of the fontimage is that all 
the printable characters for a font at a given size can be displayed in a grayscale image. 


Figure 26.19: Part of the fontimage grayscale data for 24 point Helvetica 


If the fontimage file includes the size of this image as well as the horizontal offsets for the position 
of all the characters, a function can find the grayscale value for any character and use this pixel 
array to modify another image to display text. 


The fontimage file format contains ASCII data for an identification string, the image width and 
height, and the horizontal offset in pixels of each of the characters. This is followed by the binary 
image data, one byte per pixel, in row-major order. 


Identification string 
Width and height of font image 
Horizontal offset for each character pa 
Image data, one byte per pixel, row major order 


Figure 26.20: Data format of “fontimage” file 


When the fontimage data is used in an output shader, it is read into a C struct that contains these 
values in its fields. 


typedef struct { 
int width; 
int height; 


int *x offsets; 
unsigned char *image; 
} fontimage; 


Figure 26.21: The C struct for a fontimage 


We’ll define an auxiliary function to create a fontimage struct from a fontimage file. 
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1 void miaux_load_fontimage(fontimage *fimage, char* filename) 

2 { 

3 int printable ascii size = 126 - 32 + 1; 

4 int 1, image data_size; 

5 char identifier [33]; 

6 

7 FILE* fp = fopen(filename, "r"); 

8 if (fp == NULL) 

9 mi_fatal("Could not open font image file: %s", filename) ; 
10 fscanf (fp, "%s ", identifier) ; 

11 if (stremp(identifier, "FONTIMAGE") != 0) 

12 mi_fatal("File ‘%s’ does not look like a fontimage file", filename) ; 
i 

14 fscanf(fp, "td td ", &fimage->width, &fimage->height) ; 

15 image data_size = fimage->width * fimage->height; 

16 fimage->x_offsets = 

LF (int*)mi_mem_allocate(sizeof(int) * printable ascii size); 
18 for (i = 0; i <= printable ascii size; i++) 

19 fscanf(fp, "td ", &fimage->x_offsets[il) ; 
20 fimage->image = (unsigned char*)mi_mem_allocate(image data_size) ; 
2. fread(fimage->image, image data_size, 1, fp); 
22 
23 fclose (fp) ; 
24 } 


Figure 26.22: Function miaux_load_fontimage 


Line 7 attempts to open the fontimage file; if it fails, a message is displayed and rendering stops 
with the call to mi_fatal in line 9. Before reading the data in the fontimage file, lines 10-12 
check for the identifying string FONTIMAGE in the beginning of the file. This minimal check 
will at least prevent the most egregious of memory errors that might occur if the following width 
and height values are misread. The rest of the data is read from the fontimage file with fscanf 
for the descriptive data and a final fread for the binary image data that concludes the file. 


Only printable characters are represented in a fontimage file. The characters are ordered by their 
ASCII code. The first printable ASCII character, the space character, is 32; the last printable 
character, the tilde, is 126. The total number of characters in our fontimage is therefore 95 
(line 3). We'll use the ASCII ordering to simplify the character lookup when we create text from 
the fontimage. 


Having allocated memory in miaux_load_fontimage, we’ll release the memory in a separate 
auxiliary function, miaux_release_fontimage. 


void miaux_release fontimage(fontimage *fimage) 


{ 


mi_mem_release (fimage->x_offsets) ; 
mi_mem_ release (fimage->image) ; 


Figure 26.23: Function miaux_release_fontimage 


Given a fontimage struct, we can create an array of pixels that is an image of text. This image is 
a mosaic of the various characters in the fontimage, arranged according to the order of the input 
text. Function miaux_text_image takes a fontimage and a string of text as inputs, and returns as 


Prog 398, 3.26.19. Messages 
and Errors 
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arguments the width, height and data of an array of floats that represents the grayscale image of 
the text. 


void miaux_text_image ( 
Float **text_image, int *width, int *height, 
fontimage *fimage, char* text) 


char *c; 
int i, total _width, xpos, first_printable = 32, image_size, 
index, start, end, font index, fx, fy, tx, ty, text_index; 


for (i = 0, total width = 0, c = text; i < strlen(text); i++, c++) { 
index = *c - first printable; 
start = fimage->x_offsets [index] ; 
end = fimage->x offsets [index + 1]; 
total width += end - start + 1; 
} 
*width = total width; 
*height = fimage->height; 
image size = *width * *height; 
(*text image) = (float*)mi_mem_allocate(image_size * sizeof (float) ) ; 


for (i = = text, xpos = 0; i < strlen(text); i++, c++) { 
int index = *c - first _printable; 
start = fimage->x_offsets [index] ; 
end = fimage->x_offsets [index + 1]; 
for (fy = fimage->height - 1, ty = 0; fy >= 0; fy--, ty++) { 
for (fx = start, tx = xpos; fx < end-1; fx++, tx++) { 
text index = ty * *width + tx; 
font index = fy * fimage->width + fx; 
(*text image) [text_index] = 
(float) fimage->image [font index] / 255.0; 
} 
} 


xpos += end - start + 1; 


Figure 26.24: Function miaux_text_image 


Because the characters are arranged in the fontimage in their ASCII order, we can use the numeric 
value of the character, offset by the index of the first printable character (32), to determine the 
position of the character in the fontimage offset array. In lines 9-14, we sum up the widths of 
all the characters in the text to determine how big our text image will be, the total_width of 
line 13. Given this width and the height of characters in the fontimage (fimage->height), we 
can calculate the total memory needed for the text image and allocate it in lines 15-18. 


The three nested for blocks in lines 20-33 loop for each character in the text, for each row of 
the image, and for each column of each row, converting the one-byte values in the fontimage to 
floating point values in the text image line 29 to simplify its use in compositing later on. The 
indexing variables are named with the prefix f_ for the fontimage and t_ for the text image being 
created. 


In shader annotate, we create the fontimage array and use it as the blending weight to combine 
the original image with the text color specified as a parameter. 
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struct annotate { 
miTag text; 
miTag fontimage filename; 
miInteger x; 
miInteger y; 
miColor color; 


}; 


miBoolean annotate ( 
void *result, miState *state, struct annotate *params) 
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if (params->text != miNULLTAG) { 
int x, ¥, t_x, t_y, t_width, t_heighe; 
float *text_image; 
miImg image *fb; 
fontimage fimage; 
miColor *text_color = mi_eval_color(&params->color), pixel color; 
char* text = miaux_tag to string ( 
*mi_eval_tag(&params->text), NULL) ; 
int p x = *mi_eval_integer(&params->x) , 
p_y = *mi_eval_ integer (&params->y) ; 
char* fontimage filename = 
miaux_tag_to_string(*mi_eval_ tag(&params->fontimage filename) , 
"Courier-Bold 24.fontimage") ; 


miaux_load_fontimage(&fimage, fontimage filename) ; 
miaux_text_image(&text_image, &t_width, &t_height, &fimage, text); 


fb = mi_output_image_open(state, miRC_IMAGE RGBA) ; 
for (y=p_y, t_y = 0; t_y < t_ height; y++, t_y++) { 
f (mi_par_aborted()) { 

mi progress ("Abort") ; 

break; 


( 
i 


} 
for (x = p_x, t_x = 0; t_x < t_width; x++, t_x++) { 
Float alpha = text_image[t_y * t_width + t_x]; 
hi img get color(fb,. &pixel color, x, ‘y); 
miaux_alpha_blend(&pixel_ color, text color, alpha); 
mi img put color(fb, &pixel color, x, y); 
} 
} 
miaux release fontimage (&fimage) ; 
mi output image close(state, miRC_ IMAGE RGBA) ; 


} 


return miTRUE; 


Figure 26.25: Shader source of annotate (p.583) 


Because most of the work is done by the two auxiliary functions miaux_load_fontimage in 
line 27 and miaux_text_image in line 27, the structure of shader annotate is similar to the other 
output shaders in the chapter, opening the frame buffer image in line 29, getting a pixel color in 
line 35, setting a pixel color in line 37, and closing the frame buffer image in line 41. The separate 
indices for the picture (variables p_* and the text (t_*) are used to process only those pixels in the 
image into which the text will be blended. 


26.5 Multiple output shaders 


Output shaders are called in the order in which they occur in the camera block. For output 
shaders that manipulate the standard RGBA frame buffer, any shader in the list receives the 
RGBA data as it was changed by the previous shader. 
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camera "cam" 
output "rgba" 
"letterbox" ( 
"aspect ratio" 1.778, 
"outside scale" .3 .3 .3 ) 
output "rgba" 
"annotate" ( 
"text" "HDTV aspect ratio: 16:9", 
"fontimage filename" 
"Helvetica-Bold 20.fontimage", 
"eolor"” 12 «Ss 
Wy aU, — 270 ) 
output "rgba" 
"annotate" ( 
"fontimage filename" 
"Courier-Bold 24.fontimage", 
text” "O0255205215", 
"eolor" .8.,..8. L, 
Wy" 20, ss die 7 ) 
output. "“rgba”" "Lif" "output 6.cir" 
focal: 2.5 
aperture 1 
aspect 1.333 
resolution 400 300 
end camera 


00: 55:05:15 


Figure 26.26: Using multiple output shaders 


In this case, the order of the shaders is significant—calling shader annotate first will result in 
text that is darkened by letterbox. 


26.6 Late binding and beyond 


In shader annotate, we developed the idea of a custom image file format in an attempt to create 
a portable way of compositing text into rendered images. The fontimage struct was used in two 
interrelated functions that depended upon assumptions in the fontimage design that may not be 
immediately obvious from looking at the code. Those functions also yielded to the temptation to 
write C code in a manner too familiar to computer graphics programmers, using variables with 
names like fy and nested loops that can hide inscrutable bugs. 


In this book, I’ve used the C programming language for all the shaders. The current version of 
the mental ray API libraries are written in C, and creating a layer on top of that in the miaux 
library was a good exercise in modular programming and design. However, for shaders that use 
pre-existing C++ libraries, or that need to develop complex data structures, C++ can become 
a necessity. Increasing the functionality of something like the fontimage struct might best be 
done with the support of an object-oriented language, or at least with the structures that C++ 
provides. Some programmers find that even the simpler aspects of the C++language—the “//” 
comment syntax, the declaration of variables where they are used—can make it a more readable 


language than C. 
Prog 190, 3.1. Dynamic To compile a shader in C++, you need to create the C linkage for your shader functions: the 
Linking of Shaders main shader, the version shader, and any of the init and exit shaders you may also define. The 


extern "C" qualifier before the function makes that function symbol available to mental ray at 
run-time. 
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ii Cee 
#include "shader.h" 


extern *C" 
int negate version(void) { return 1; } 


extern "C" 
miBoolean negate(void *result, miState *state, void *params) 


{ 


miImg_image *fb = mi_output_image open(state, miRC_IMAGE RGBA) ; 
for (int y = 0; y < state->camera->y resolution; y++) { 


for (int x = 0; x < state->camera->x_resolution; x++) { 
miColor pixel; 
mi_img get _color(fb, &pixel, x, y); 
pixel.r = 1.0 - pixel.r; 
pixel.g 1.0 - pixel.g; 
pixel.b = 1.0 - pixel.b; 
mi_img put_color(fb, &pixel, x, y); 
} 
} 
mi_output_image_close(state, miRC_IMAGE_ RGBA) ; 
return miTRUE; 


Figure 26.27: Source code for shader negate with linkage defined by the extern "C" qualifier 


Shaders compiled in C++ can be used with other shaders; the run-time linking of the libraries 
are handled in the same manner by mental ray. 


camera "cam" 
eutput.."rgba"™ 
"letterbox" ( 
"aspect ratio" 1.778, 
"outside Scale”..3 .3 .3 ) 
output "rgba" 
"annotate" ( 
"text" "HDTV aspect ratio: 16:9", 
"fontimage filename" 
"Helvetica-Bold 20.fontimage", 
"eolor"™ 1.2 «SB, 
Wy" 20, — 270 ) 
output "rgba" 
"annotate" ( 
"fontimage filename" 
"Courier-Bold 24.fontimage", 
"text" "00:55:05:15", 
teoler”™ .8 .8 1, 
Wy 20, sa dl 7 ) 
output "rgba" 
"negate" () 
output "rgba" "Cit" “output 7.12" 
focal 1.5 
aperture 1 
aspect 1.333 
resolution 400 300 
end camera 


Figure 26.28: Mixing shaders written in C and C++ 
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Appendices 


Appendix A 


Rendered scene files 


This appendix contains rendered images from the scene files used as examples throughout the 
book labeled with the page number on which the image appears. 
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Chapter 6 — Color from orientation 
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Chapter 7 — Color from position 
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Chapter 8 — The transparency of a surface 
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Chapter 9 — Color from functions 
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Chapter 10 — The color of edges 
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Chapter 10 — The color of edges 
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Chapter 11 — Lights 
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Chapter 12 — Light on a surface 
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Chapter 13 — Shadows 
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Chapter 14 — Reflection 
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Chapter 15 — Refraction 
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Chapter 16 — Light from other surfaces 465 


Chapter 16 — Light from other surfaces 
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Chapter 17 — Modifying surface geometry 
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Chapter 19 — Creating geometric objects 


Chapter 18 — Modifying surface orientation 
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Chapter 19 — Creating geometric objects 


Page 277 


Page 283 


Page 285 


Page 288 


Page 267 


468 A Rendered scene files 


Chapter 20 — Modeling hair 
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Chapter 21 — The environment of the scene 
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Chapter 21 — The environment of the scene 


Page 339 


Page 350 Page 325 Page 354 


470 A Rendered scene files 


Page 356 


Chapter 22 — A visible atmosphere 
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Chapter 24 — Changing the lens 471 


Chapter 23 — Volumetric effects 
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Chapter 25 — Rendering image components 473 
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Chapter 26 — Modifying the final image 
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Appendix B 


Shader source code 


This appendix lists the complete source code for all the shaders in the book. The declaration in 
.mi syntax is listed first, followed by the full shader source code. If the shader contains miaux 
auxiliary functions, they are listed after the shader source code with the page number of the 
function definition. The header file for the miaux functions begins on page 585. The source code 
for the miaux functions follows the header file on page 589. 


The DLLEXPORT macro declared in shader.h is required for compilation under Microsoft 
Windows, but is unnecessary and is ignored during compilation under Unix-based systems 
such as Linux and Mac OS X. The first shader, one_color, demonstrates the use of DLLEXPORT. 
For all other shaders, it should be added for the main shader function, as well as the version 
function and the init and exit functions, if they exist. 


476 B Shader source code 


one color Page 52 


declare shader 
color "one_color" ( 
color "color" default 111 ) 


version 1 
apply material 
end declare 


#include "shader.h" 


DLLEXPORT 
int one_color_version(void) { return 1; } 


struct one_color { 
miColor color; 


}3 


DLLEXPORT 
miBoolean one_color ( 
miColor *result, miState *state, struct one_color *params ) 


{ 
*xresult = *mi_eval_color(&params->color) ; 
return miTRUE; 
F 
Front-bright Page 58 


declare shader 
color "front_bright" ( 
color "tint" default 1i11 ) 


version 1 
apply material 
end declare 


#include "shader.h" 


struct front_bright { 
miColor tint; 


}; 
int front_bright_version(void) { return(1); } 


miBoolean front_bright ( 

miColor *result, miState *state, struct front_bright *params  ) 
{ 

miColor *tint = mi_eval_color(&params->tint) ; 

miScalar scale = -state->dot_nd; 

result->r = tint->r * scale; 

result->g = tint->g * scale; 

result->b = tint->b * scale; 

result->a = 1.0; 

return miTRUE; 
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declare shader 
color "front_bright_dot" ( 
color “tint” default 1 11) 


version 1 
end declare 


#include "shader.h" 


struct front_bright_dot { 
miColor tint; 


}; 
int front_bright_dot_version(void) { return(1); } 


miBoolean front_bright_dot ( 

miColor *result, miState *state, struct front_bright_dot *params ) 
1 

miColor *tint = mi_eval_color(&params->tint) ; 

miScalar scale = -mi_vector_dot(&state->normal, &state->dir); 

result->r = tint->r * scale; 

result->g = tint->g * scale; 

result->b = tint->b * scale; 

result->a = 1.0; 

return miTRUE; 
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declare shader 
color "normals_as_colors" () 
version 1 


apply material, texture 
end declare 


#include "shader.h" 
int normals_as_colors_version(void) { return(1); } 


miBoolean normals_as_colors ( 

miColor *result, miState *state, void *params ) 
{ 

miVector normal; 

mi_vector_to_object(state, &normal, &state->normal) ; 

mi_vector_normalize(&normal) ; 

result->r = normal.x / 2.0 + 

result->g = normal.y / 2.0 + .5; 

result->b normal.z / 2.0 + .5; 

result->a = 1.0; 

return miTRUE; 


. 
> 


.5 
.o 
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declare shader 
color "depth_fade" ( 
scalar "near", 


Scalar "Zar" ) 
version 1 
apply material 
end declare 


#include "shader.h" 


struct depth_fade { 
miScalar near; 
miScalar far; 


}; 
int depth_fade_version(void) { return(1); } 


miBoolean depth_fade ( 
miColor *result, miState *state, struct depth_fade *params ) 


4. 
miScalar near = *mi_eval_scalar(&params->near) ; 
miScalar far = *mi_eval_scalar(&params->far) ; 
miScalar zpos = state->point.z, factor; 
if (zpos > near) 
factor = 1.0; 
else if (zpos < far) 
factor = 0.0; 
else 
factor = (zpos - far) / (near - far); 
result->r = result->g = result->b = factor; 
return miTRUE; 
t 
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declare shader 
color "depth_fade_tint" ( 
scalar "near", 
color "near_color" default 1 1 1, 


scalar "far", 
color "far_color" default 0 00 ) 
version 1 
apply material 
end declare 


#include "shader.h" 


struct depth_fade_tint { 
miScalar near; 
miColor near_color; 
miScalar far; 
miColor far_color; 


depth_fade_tint_2 479 


int depth_fade_tint_version(void) { return(1); } 


miBoolean depth_fade_tint ( 
miColor *result, miState *state, struct depth_fade_tint *params ) 


{ 
miScalar near = *mi_eval_scalar (&params->near) ; 
miColor *near_color = mi_eval_color(&params->near_color) ; 
miScalar far = *mi_eval_scalar(&params->far) ; 
miColor *far_color = mi_eval_color(&params->far_color) ; 
miScalar zpos = state->point.z, factor; 
if (zpos > near) 
factor = 1.0; 
else if (zpos < far) 
factor = 0.0; 
else 
factor = (zpos - far) / (near - far); 
result->r = near_color->r * factor + far_color->r * (1.0 - factor); 
result->g = near_color->g * factor + far_color->g * (1.0 - factor); 
result->b = near_color->b * factor + far_color->b * (1.0 - factor); 
return miTRUE; 
t 
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declare shader 
color "depth_fade_tint_2" ( 
scalar "near", 
color "near_color" default i 1 1, 


scalar “far. 
color "far_color" default 000 ) 
version 1 
end declare 


#include "shader.h" 
#include "miaux.h" 


struct depth_fade_tint_2 { 
miScalar near; 
miColor near_color; 
miScalar far; 
miColor far_color; 


}; 
int depth_fade_tint_2_version(void) { return(1); } 


miBoolean depth_fade_tint_2 ( 

miColor *result, miState *state, struct depth_fade_tint_2 *params ) 
{ 

miScalar near = *mi_eval_scalar(&params->near) ; 

miColor *near_color = mi_eval_color(&params->near_color) ; 

miScalar far = *mi_eval_scalar(&params->far) ; 

miColor *far_color = mi_eval_color(&params->far_color) ; 


miaux_blend_colors(result, near_color, far_color, 
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miaux_fit(state->point.z, far, near, 0,0, 1,0)); 


return miTRUE; 


} 
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declare shader 
color "depth_fade_tint_3" ( 
scalar "near", 
color "“near_color" default 1 i 1, 


scalar "far", 
color "far_color" default 0 0 0 ) 
version 1 
end declare 


#include "shader.h" 
#include "miaux.h" 


struct depth_fade_tint_3 { 
miScalar near; 
miColor near_color; 
miScalar far; 
miColor far_color; 


}; 
int depth_fade_tint_3_version(void) { return(1); } 


miBoolean depth_fade_tint_3 ( 
miColor *result, miState *state, struct depth_fade_tint_3 *params ) 


{ 
miaux_blend_colors(result, 
mi_eval_color(&params->near_color) , 
mi_eval_color(&params->far_color) , 
miaux_fit(state->point.z, 
*mi_eval_scalar(&params->far) , 
*mi_eval_scalar(&params->near) , 
o.0, 1.0)); 
return miTRUE; 
} 
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declare shader 
color "transparent" ( 
color "color" default 111 1, 
color "transparency" default .5 .5 .5 ) 


version 1 
apply material 
end declare 


#include "shader.h" 
#include "miaux.h" 


struct transparent { 
miColor color; 
miColor transparency; 


yi 


int transparent_version(void) { return(1); } 


miBoolean transparent ( 
miColor *result, miState *state, struct transparent *params ) 


{ 
miColor *transparency = mi_eval_color(&params->transparency) ; 
if (transparency->r == 0.0 && transparency->g == 0.0 && 
transparency->b == 0.0 && transparency->a == 0.0) 
*xresult = *mi_eval_color(&params->color) ; 
else { 
mi_trace_transparent (result, state ); 
if (!(transparency->r == 1.0 && transparency->g == 1.0 && 
transparency->b == 1.0 && transparency->a == 1.0)) { 
miColor *color = mi_eval_color(&params->color) ; 
miColor opacity; 
opacity.r = 1.0 - transparency->r; 
opacity.g = 1.0 - transparency->g; 
opacity.b = 1.0 - transparency->b; 
opacity.a = 1.0 - transparency->a; 
mi_opacity_set(state, opacity) ; 
result->r = result->r * transparency->r + color->r * opacity.r; 
result->g = result->g * transparency->g + color->g * opacity.g; 
result->b = result->b * transparency->b + color->b * opacity.b; 
t 
t 
return miTRUE; 
t 
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declare shader 
color "transparent_modularized" ( 
color "color" default ii 1 1, 
color "transparency" default .5 .5 .5 .5 ) 


version 1 
apply material 
end declare 
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#include "shader.h" 
#include "miaux.h" 


struct transparent_modularized { 
miColor color; 
miColor transparency; 


F} 


int transparent_modularized_version(void) { return(1); } 


miBoolean transparent_modularized ( 
miColor *result, miState *state, struct transparent_modularized *params ) 


{ 
miColor *transparency = mi_eval_color(&params->transparency) ; 
if (miaux_all_channels_equal(transparency, 0.0)) 
*result = *mi_eval_color(&params->color) ; 
else if (miaux_all_channels_equal(transparency, 1.0)) 
mi_trace_transparent (result, state); 
else { 
miColor *color = mi_eval_color(&params->color), opacity; 
mi_trace_transparent(result, state) ; 
miaux_invert_channels(&opacity, transparency) ; 
mi_opacity_set(state, &Xopacity) ; 
miaux_blend_channels(result, color, transparency) ; 
} 
return miTRUE; 
} 
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declare shader 
color "show_uv" ( 
boolean "u" default on, 


boolean "v" default on ) 
version 1 
apply material, texture 
end declare 


#include "shader.h" 


struct show_uv { 
miBoolean u; 
miBoolean v; 


¥3 


int show_uv_version(void) {return 1i;} 
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miBoolean show_uv ( 
miColor *result, miState *state, struct show_uv *params ) 
{ 
result->r = result->g = result->b = 0; 
if (*mi_eval_boolean(&params->uw) ) 
result->r = state->tex_list[0].x; 
if (*mi_eval_boolean(&params->v) ) 
result->g = state->tex_list[0].y; 
return miTRUE; 
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declare shader 
color "show_uv_steps" ( 
integer "u_count" default 4, 


integer "v_count" default 4 ) 
version 1 
apply material, texture 
end declare 


#include "shader.h" 
struct show_uv_steps { 
miInteger u_count; 
milnteger v_count; 
I; 


int show_uv_steps_version(void) {return 1;} 


miScalar quantize(miScalar value, miInteger count) 


{ 
miScalar gq = (miScalar)count; 
if (count < 2) 
return q; 
else 
return (miScalar)((int) (value * q) / (q - 1)); 
i 


miBoolean show_uv_steps ( 
miColor *result, miState *state, struct show_uv_steps *params ) 


{ 


result->r quantize(state->tex_list[0].x, 
*mi_eval_integer (&params->u_count) ) ; 
result->g = quantize(state->tex_list[0].y, 
*mi_eval_integer (&params->v_count) ) ; 
result->b = 0; 
return miTRUE; 
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declare shader 
color "texture_uv_simple" ( 
color texture "tex" ) 


version 1 
apply material, texture 
end declare 


#include "shader.h" 

struct texture_uv_simple { 
miTag tex; 

}; 


int texture_uv_simple_version(void) { return 1; } 


miBoolean texture_uv_simple ( 
miColor *result, miState *state, struct texture_uv_simple *paras ) 


a 
mi_lookup_color_texture ( 
result, state, *mi_eval_tag(&paras->tex), &state->tex_list[0]); 
return miTRUE; 
} 
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declare shader 
color "texture_uv" ( 
color texture "tex", 
scalar "u_scale" default 1, 
scalar "v_scale" default i, 


scalar "u_offset" default 0, 
scalar "v_offset" default 0 ) 
version 1 
apply material, texture 
end declare 


#include "shader.h" 
#include <math.h> 


struct texture_uv { 
miTag tex; 
miScalar u_scale; 
miScalar v_scale; 
miScalar u_offset; 
miScalar v_offset; 


}; 
int texture_uv_version(void) {return 1;} 


miBoolean texture_uv ( 

miColor *result, miState *state, struct texture_uv *params ) 
{ 

miVector uv_coord = {0.0, 0.0, 0.0}; 
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miScalar u_scale = *mi_eval_scalar(&params->u_scale) ; 
miScalar v_scale = *mi_eval_scalar(&params->v_scale) ; 
miScalar u_offset = *mi_eval_scalar (&params->u_offset) ; 
miScalar v_offset = *mi_eval_scalar (&params->v_offset) ; 


uv_coord.x = fmod((state->tex_list[0].x * u_scale) + u_offset, 1.0); 
uv_coord.y = fmod((state->tex_list[0].y * v_scale) + v_offset, 1.0); 


mi_lookup_color_texture ( 
result, state, *mi_eval_tag(&params->tex), &uv_coord) ; 


return miTRUE; 
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declare shader 
color "vertex_color" ( 
integer "uv_index" default 0 ) 


version 1 
apply material, texture 
end declare 


#include "shader.h" 


struct vertex_color { 
miInteger uv_index; 


iF 
int vertex_color_version(void) { return 1; } 


miBoolean vertex_color ( 
miColor *result, miState *state, struct vertex_color *params ) 
{ 


miInteger uv_index = *mi_eval_integer (&params->uv_index) ; 


state->tex_list [uv_index].x; 
state->tex_list [uv_index] .y; 
state->tex_list [uv_index] .z; 


result->r 
result-—>g 
result->b 


return miTRUE; 
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declare shader 
color "summed_noise_color" ( 
scalar "point_scale" default 1, 
scalar "octave_scaling" default 2, 
scalar "summing_weight" default 2, 
integer "number_of_octaves" default 


scalar "red_exponent" default 1, 

scalar "green_exponent" default 1, 

scalar "blue_exponent" default 1 ) 
version 1 


apply material, texture 
end declare 


#include "shader.h" 
#include "miaux.h" 


struct summed_noise_color { 
miScalar point_scale; 
miScalar octave_scaling; 
miScalar summing_weight; 
milnteger number_of_octaves; 
miScalar red_exponent ; 
miScalar green_exponent ; 
miScalar blue_exponent ; 


Ti 
int summed_noise_color_version(void) { return(1i); } 


miBoolean summed_noise_color ( 
miColor *result, miState *state, struct summed_noise_color *params ) 
{ 
miScalar noise_sum; 
miScalar red_exponent = *mi_eval_scalar(&params->red_exponent) ; 
miScalar green_exponent = *mi_eval_scalar(&params->green_exponent) ; 
miScalar blue_exponent = *mi_eval_scalar (&params->blue_exponent) ; 
miVector object_point ; 
mi_point_to_object(state, &object_point, &state->point) ; 
mi_vector_mul(&xobject_point, *mi_eval_scalar(&params->point_scale)) ; 


noise_sum = 
miaux_summed_noise(&object_point, 
*mi_eval_scalar(&params->summing weight) , 
*mi_eval_scalar (&params->octave_scaling) , 
*mi_eval_integer (kparams->number_of_octaves) ) ; 


result->r = 

red_exponent == 1 ? noise_sum : pow(noise_sum, red_exponent) ; 
result->g = 

green_exponent == 1 ? noise_sum : pow(noise_sum, green_exponent) ; 
result->b = 

blue_exponent == 1 ? noise_sum : pow(noise_sum, blue_exponent) ; 


return miTRUE; 
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declare shader 
struct { geometry "instance", 
vector "normal" } 


"c_store" () 
version 1 
apply texture 
end declare 


#include "shader.h" 
#include "contour_info.h" 


int c_store_version(void) { return 1; } 


miBoolean c_store ( 
void *info_pointer, 
ant *info_size, 
miState *state, 
miColor *color ) 


1 
contour_info *info = (contour_info*)info_pointer; 
info->instance = state->instance; 
info->normal = state->normal; 
*info_size = sizeof (contour_info) ; 
return miTRUE; 
} 
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declare shader 
"s contrast” ¢ 
scalar "dot_threshold" default 0.71, ) 


version 1 
apply texture 
end declare 


#include "contour_structs.h" 


struct’ c_contrast { 
miScalar dot_threshold; 
iF 


int c_contrast_version(void) { return 1; } 
miBoolean c_contrast ( 


contour_info *infol, 
contour_info *info2, 
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int level, 
miState *state, 
struct c_contrast *params  ) 


if (infoi == NULL || 
info2 == NULL || 
infoi->instance != info2->instance || 
(mi_vector_dot(&infoi->normal, &info2->normal) < 
*mi_eval_scalar(&params->dot_threshold) ) ) 
return miTRUE; 

else 
return miFALSE; 
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declare shader 
"ec contour” ( 
color "color" default 0 0 0 1, 
scalar "width" default 1 ) 


version 1 
apply texture 
end declare 


#include "shader.h" 
#include "contour_info.h" 


struct. c_contour { 
miColor color; 
miScalar width; 


ti 
int c_contour_version(void) { return 1; } 


miBoolean c_contour ( 
miContour_endpoint *result, 


contour_info *info_near, 
contour_info *info_far, 
miState *state, 
struct c_contour *params ) 
{ 
result->color = *mi_eval_color(&params->color) ; 
result->width = *mi_eval_scalar(&params->width) ; 
return miTRUE; 
} 
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declare shader 
"c_output" ( 
string "postscript_filename" ) 


version i 
apply output 
end declare 


c_output 


#include "shader.h" 
#include "miaux.h" 


struct c_output { 


ia 


miTag postscript_filename; 


int c_output_version(void) { return 1; } 


miBoolean c_output ( 


1 


miColor *result, miState *state, struct c_output *params ) 


miContour_endpoint pil; 
miContour_endpoint p2; 


FILE* fp; 
char* postscript_filename = 


miaux_tag_to_string(*mi_eval_tag(&params->postscript_filename), NULL) ; 


if (postscript_filename == NULL) 
postscript_filename = "contour_output.ps"; 


mi_progress("Writing contour PostScript data to file fs", 
postscript_filename) ; 


fp = fopen(postscript_filename, "w"); 

fprintiifip, “AA! wn"): 

fprintf(fp, "%Z444BoundingBox: 0 0 %d %d\n", 
state->camera->x_resolution, state->camera->y_resolution) ; 


while (mi_get_contour_line(&p1, &p2)) 
fprintf(fp, "%g %g moveto tg hg lineto stroke\n", 
pl. point.%, Pi.point.y7, 
p2.point.x, p2.point.y) ; 


fprintf(fp, "showpage\n") ; 
fclose(fp); 


return miTRUE; 
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c_tessellate Page 108 


declare shader 
struct { integer "prim_index" } 
"c_tessellate_store" () 
version 1 
apply texture 
end declare 


declare shader 
"c_ tessellate_contrast"™ () 
version i 


apply texture 
end declare 


declare shader 
"c_tessellate_contour" ( 
color “color” default 0 0 6 1, 
scalar "width" default 1 ) 
version 1 
apply texture 
end declare 


#include "shader.h" 
/* Info struct */ 


typedef struct { 
int primitive_index; 
} c_tessellate_info; 


/* Store shader */ 
int c_tessellate_store_version(void) { return 1; } 


miBoolean c_tessellate_store ( 
void *info_pointer, 
int *info_size, 
miState *state, 
miColor *color) 


{ 
c_tessellate_info *info = (c_tessellate_info*)info_pointer; 
int primitive_index; 
mi_query(miQ_PRI_INDEX, state, 0, &primitive_index) ; 
info->primitive_index = primitive_index; 
*info_size = sizeof(c_tessellate_info) ; 
return miTRUE; 

t 


/* Contrast shader */ 
int c_tessellate_contrast_version(void) { return 1; } 


miBoolean c_tessellate_contrast ( 
c_tessellate_info *infol, 
c_tessellate_info *info2, 
int level, 
miState *state, 
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void *params) 


{ 
if (infol == NULL || 
info2 == NULL || 
infoi->primitive_index != info2->primitive_index) 
return miTRUE; 
else 
return miFALSE; 
} 


/* Contour shader */ 


struct c_tessellate_contour { 
miColor color; 
miScalar width; 


Ps 
int c_tessellate_contour_version(void) ‘{ return 1; } 


miBoolean c_tessellate_contour ( 
miContour_endpoint *result, 
c_tessellate_info *info_near, 
c_tessellate_info *info_far, 
miState *state, 
struct c_tessellate_contour *params) 


4. 
result->color = *mi_eval_color(&params->color) ; 
result->width = *mi_eval_scalar(&params->width) ; 
return miTRUE; 
} 
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declare shader 
color "show_barycentric" ( 
eclor "a" defanlt 1 .3 .3, 
color "b" default .3 1 .3, 


color “c" defanlt .3 .3 1 ) 
version 1 
apply material 
end declare 


#include "shader.h" 
#include "miaux.h" 


struct show_barycentric { 
miColor a; 
miColor b; 
miColor c; 


I; 
int show_barycentric_version(void) {return 1;} 


miBoolean show_barycentric ( 
miColor *result, miState *state, struct show_barycentric *params  ) 
{ 


miaux_add_scaled_color(result, mi_eval_color(&params->a), state->bary[0]); 
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miaux_add_scaled_color(result, mi_eval_color(&params->b), state->bary[1]); 
miaux_add_scaled_color(result, mi_eval_color(&params->c), state->bary[2]); 
return miTRUE; 


} 
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declare shader 
color "front_bright_steps" ( 
color "tint" default i 1 1, 


integer "steps" default 3 ) 
version 1 
apply material 
end declare 


#include "shader.h" 
#include "miaux.h" 


struct front_bright_steps { 
miColor tint; 
miinteger steps; 


}; 
int front_bright_steps_version(void) { return(1); } 


miBoolean front_bright_steps ( 

miColor *result, miState *state, struct front_bright_steps *params  ) 
{ 

miColor *tint = mi_eval_color(&params->tint) ; 

miScalar scale = 

miaux_quantize(-state->dot_nd, *mi_eval_integer (&params->steps) ) ; 

result->r = tint->r * scale; 

result->g = tint->g * scale; 

result->b = tint->b * scale; 

result->a = 1.0; 

return miTRUE; 
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declare shader 
struct { geometry "instance", 
ealor “color, 
vector "normal" } 
"c_toon_store" () 
version 1 
apply texture 
end declare 


declare shader 
"ce toon_contrast" ( 
scalar "dot_threshold" default 0.71 ) 


version 1 
apply texture 
end declare 


declare shader 
"es toon contour" { 
color "color" default 0 00 i, 
scalar "width" default 1 ) 
version 1 
apply texture 
end declare 


#include "shader.h" 
#include "miaux.h" 


typedef struct { 
miTag instance; 
miVector normal; 
miColor color; 

} c_toon_info; 


int c_toon_store_version(void) { return 1; } 


miBoolean c_toon_store ( 
void *info_pointer, int *info_size, miState *state, miColor *color) 
{ 


c_toon_info *info = (c_toon_info*)info_pointer; 


info->instance = state->instance; 
info->normal = state->normal; 
info->color = *color; 

*info_size = sizeof(c_toon_info) ; 


return miTRUE; 


Ls 


struct c_toon_contrast { 
miScalar dot_threshold; 
ie 


int c_toon_contrast_version(void) { return 1; } 


miBoolean c_toon_contrast ( 
c_toon_info *infoil, c_toon_info *info2, int level, miState x*state, 
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struct c_toon_contrast *params ) 


{ 
if (infol == NULL || 
info2 == NULL || 
infoi->instance != info2->instance || 
(mi_vector_dot(&infoi->normal, &info2->normal) < 
*mi_eval_scalar(&params->dot_threshold)) || 
infol->color.r != info2->color.r || 
infoi->color.g != info2->color.g || 
infol->color.b != info2->color.b) 
return miTRUE; 
else 
return miFALSE; 
i 


struct c_toon_contour { 
miColor color; 
miScalar width; 


i 
int c_toon_contour_version(void) {return 1; } 
miBoolean c_toon_contour ( 


miContour_endpoint *result, c_toon_info *info_near, c_toon_info *info_far, 
miState *state, struct c_toon_contour *params ) 


{ 
result->color = *mi_eval_color(&params->color) ; 
result->width = *mi_eval_scalar(&params->width) ; 
return miTRUE; 
} 
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declare shader 
color "lambert_steps" ( 
color "ambient" default O O O, 
color "diffuse" default 111 
integer "steps" default 3, 


> 


array light "lights" ) 
version 1 
apply material 
end declare 


#include "shader.h" 
#include "miaux.h" 


struct lambert_steps { 
miColor ambient; 
miColor diffuse; 
milnteger steps; 
int i_light ; 
int n_light ; 
miTag light[1]; 

}; 


int lambert_steps_version(void) { return 1; } 
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miBoolean lambert_steps ( 

miColor *result, miState *state, struct lambert_steps *params  ) 
{ 

int i, light_count, light_sample_count ; 

miColor sum, light_color; 

miScalar dot_nl; 

miTag *light; 


miColor *diffuse = mi_eval_color(&params->diffuse) ; 
miInteger steps = *mi_eval_integer(xparams->steps) ; 
miaux_light_array(&light, &light_count, state, 

&params->i_light, &params->n_light, params->light) ; 
*result = *mi_eval_color(&params->ambient) ; 


for (i = 0; 1 < light_count; i++, light++) { 
miaux_set_channels(&sum, 0); 
light_sample_count = 0; 
while (mi_sample_light(&light_color, NULL, &dot_nl, 
state, *light, &light_sample_count)) { 
dot_nl = miaux_quantize(dot_nl, steps); 
miaux_add_diffuse_component(&sum, dot_nl, diffuse, &light_color) ; 
t 
if (light_sample_count) 
miaux_add_scaled_color(result, &sum, 1.0/light_sample_count) ; 
t 


return miTRUE; 
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declare shader 
color "point_light" ( 
color "light_color" default 


version 1 
apply light 
end declare 


#include "shader.h" 


struct point_light { 
miColor light_color; 


}; 
int point_light_version(void) { return 1; } 


miBoolean point_light ( 

miColor *result, miState *state, struct point_light *params ) 
{ 

*xresult = *mi_eval_color(&params->light_color) ; 

return miTRUE; 
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point_light_shadow Page 167 


declare shader 
color "point_light_shadow" ( 
color "light_color" default 11 1 ) 


version 1 
apply light 
end declare 


#include "shader.h" 

struct point_light_shadow { 
miColor light_color; 

}; 


int point_light_shadow_version(void) { return 1; } 


miBoolean point_light_shadow ( 
miColor *result, miState *state, struct point_light_shadow *params ) 


{ 
*xresult = *mi_eval_color(&params->light_color) ; 
return mi_trace_shadow(result, state); 
} 
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declare shader 
color "spotlight" ( 
color "light_color" default 111, ) 


version 1 
apply light 
end declare 


#include "shader.h" 
#include "miaux.h" 


struct spotlight { 
miColor light_color; 


}; 
int spotlight_version(void) { return 1; } 


miBoolean spotlight ( 

miColor *result, miState *state, struct spotlight *params ) 
{ 

miTag light_tag = miaux_current_light_tag(state) ; 


if (miaux_offset_spread_from_light(state, light_tag) 
> miaux_light_spread(state, light_tag)) { 
*result = *mi_eval_color(&params->light_color) ; 
return mi_trace_shadow(result, state); 

} 


else 
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return miFALSE; 


t 
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declare shader 
color "soft_spotlight" ( 
color "light_color" default 111, 
1 ) 


scalar "inner_spread" default 
version 1 
apply light 
end declare 


#include "shader.h" 
#include "miaux.h" 


struct soft_spotlight { 
miColor light_color; 
miScalar inner_spread; 


}; 
int soft_spotlight_version(void) { return 1; } 


miBoolean soft_spotlight ( 
miColor *result, miState *state, struct soft_spotlight *params ) 
{ 
miScalar inner_spread, attenuation; 
miTag light_tag = miaux_current_light_tag(state) ; 
miScalar offset_spread = miaux_offset_spread_from_light (state, light_tag) ; 
miScalar light_spread = miaux_light_spread(state, light_tag) ; 


if (offset_spread < light_spread) 
return miFALSE; 


*result = *mi_eval_color(&params->light_color) ; 
inner_spread = *mi_eval_scalar(&params->inner_spread) ; 


if (offset_spread < inner_spread) { 
attenuation = miaux_fit(offset_spread, inner_spread, light_spread, 1, 0); 
miaux_scale_color(result, attenuation) ; 

t 


return mi_trace_shadow(result, state); 
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Sinusoid soft_spotlight Page 142 


declare shader 
color "sinusoid_soft_spotlight" ( 
color "light_color" default i 1 1, 
scalar "inner_spread" default 1 ) 


version 1 
apply light 
end declare 


#include "shader.h" 
#include "miaux.h" 


struct sinusoid_soft_spotlight { 
miColor light_color; 
miScalar inner_spread; 


}; 
int sinusoid_soft_spotlight_version(void) { return 1; } 


miBoolean sinusoid_soft_spotlight ( 
miColor *result, miState *state, struct sinusoid_soft_spotlight *params ) 
{ 
miScalar inner_spread, attenuation; 
miTag light_tag = miaux_current_light_tag(state) ; 
miScalar offset_spread = miaux_offset_spread_from_light (state, light_tag) ; 
miScalar light_spread = miaux_light_spread(state, light_tag) ; 


if (offset_spread < light_spread) 
return miFALSE; 


*result = *mi_eval_color(&params->light_color) ; 
inner_spread = *mi_eval_scalar (&params->inner_spread) ; 


if (offset_spread < inner_spread) { 
attenuation = 
miaux_sinusoid_fit(offset_spread, inner_spread, light_spread, 1, 0); 
miaux_scale_color(result, attenuation) ; 


} 


return mi_trace_shadow(result, state); 
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point_light_falloff Page 147 


declare shader 
color "point_light_falloff" ( 
color "light_color" default 11 1 ) 


version 1 
apply light 
end declare 


#include <math.h> 
#include "shader.h" 
#include "miaux.h" 


struct point_light_falloff { 
miColor light_color; 


}; 
int point_light_falloff_version(void) {return(1) ;} 


miBoolean point_light_falloff ( 
miColor *result, miState *state, struct point_light_falloff *params ) 


1 
miTag light; 
miScalar exponent ; 
*xresult = *mi_eval_color(&params->light_color) ; 
mi_query(miQ_INST_ITEM, state, state->light_instance, &light) ; 
mi_query(miQ_LIGHT_EXPONENT, state, light, &exponent) ; 
miaux_scale_color(result, 1.0 / pow(state->dist, exponent) ) ; 
return mi_trace_shadow(result, state); 
} 
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declare shader 
color "lambert" ( 
color "ambient" default O O 0, 
color "diffuse" default 1 1 1, 


array light "lights" ) 
version 1 
apply material 
end declare 


#include "shader.h" 
#include "miaux.h" 


struct lambert { 
miColor ambient; 
miColor diffuse; 
int 1_light ; 
int n_light ; 
miTag light[i]; 
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¥t 
int lambert_version(void) { return i; } 


miBoolean lambert ( 
miColor *result, miState *state, struct lambert *params  ) 


{ 
int i, light_count, light_sample_count; 
miColor sum, light_color; 
miScalar dot_nl; 
miTag *light; 
miColor *diffuse = mi_eval_color(&params->diffuse) ; 
miaux_light_array(&light, &light_count, state, 
&params->i_light, &params->n_light, params->light) ; 
*xresult = *mi_eval_color(&params->ambient) ; 
for (i = 0; i < light_count; i++, light++) { 
miaux_set_channels(&sum, 0); 
light_sample_count = 0; 
while (mi_sample_light(&light_color, NULL, &dot_nl, 
state, *light, &light_sample_count) ) 
miaux_add_diffuse_component (sun, dot_nl, diffuse, &light_color) ; 
if (light_sample_count) 
miaux_add_scaled_color(result, &sum, 1.0/light_sample_count) ; 
} 
return miTRUE; 
} 
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declare shader 
color "phong" ( 
color "ambient" default 0 0 0O, 
color "diffuse" default 11 1, 
color "specular" default 0 0 0, 


scalar "exponent" default 30, 
array light "lights" ) 
version 1 
apply material 
end declare 


#include "shader.h" 
#include "miaux.h" 


struct phong { 
miColor ambient; 
miColor diffuse; 
miColor specular; 
miScalar exponent ; 
int i_light ; 
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phong 


he 


int n_light ; 
miTag light [1]; 


int phong_version(void) { return 1; } 


miBoolean phong ( 


{ 


miColor *result, miState *state, struct phong *params  ) 


int 1, light_count, light_sample_count; 
miColor sum, light_color; 

miVector direction_toward_light ; 
miScalar dot_nl; 

miTag *light; 


miColor *diffuse = mi_eval_color(&params->diffuse) ; 
miColor *specular = mi_eval_color(&params->specular) ; 
miScalar exponent = *mi_eval_scalar(&params->exponent) ; 
miaux_light_array(&light, &light_count, state, 

&params->i_light, &params->n_light, params->light) ; 
*xresult = *mi_eval_color(&params->ambient) ; 


for (i = 0; i < light_count; i++, light++) { 
miaux_set_channels(&sum, 0); 
light_sample_count = 0; 
while (mi_sample_light(&light_color, &direction_toward_light, &dot_nl, 
state, *light, &light_sample_count)) { 
miaux_add_diffuse_component(&sum, dot_nl, diffuse, &light_color) ; 
miaux_add_phong_specular_component(&sum, state, exponent, 
&direction_toward_light, 
specular, &light_color) ; 
} 
if (light_sample_count) 
miaux_add_scaled_color(result, &sum, 1.0/light_sample_count) ; 
r 


return miTRUE; 
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declare shader 
color “blim” ( 
color "ambient" default 0 0 O, 
color "diffuse" default 1i1 1, 
color "specular" default 0 0 0, 
scalar "avg_microfacet_slope" default .2, 


scalar "index_of_refraction" default 3, 
array light "lights" ) 
version 1 
apply material 
end declare 


#include "shader.h" 
#include "miaux.h" 


struct blinn { 
miColor ambient; 
miColor diffuse; 
miColor specular; 
miScalar avg_microfacet_slope; 
miScalar index_of_refraction; 
int i_light ; 
int n_light ; 
miTag light [1]; 
}; 


int blinn_version(void) { return i; } 


miBoolean blinn ( 

miColor *result, miState *state, struct blinn *params ) 
{ 

int i, light_count, light_sample_count ; 

miColor sum, light_color; 

miVector direction_toward_light ; 

miScalar dot_nl; 

miTag *light; 


miColor *diffuse = mi_eval_color (&params->diffuse) ; 

miColor *specular = mi_eval_color(&params->specular) ; 

miScalar avg_microfacet_slope = *mi_eval_scalar(&params->avg_microfacet_slope) ; 
miScalar index_of_refraction = *mi_eval_scalar(&params->index_of_refraction) ; 


miaux_light_array(&light, &light_count, state, 
&params->i_light, &params->n_light, params->light) ; 
*xresult = *mi_eval_color(&params->ambient) ; 


for (i = 0; i < light_count; it+, light++) { 
miaux_set_channels(&sum, 0); 
light_sample_count = 0; 
while (mi_sample_light(&light_color, &direction_toward_light, &dot_nl, 
state, *light, &light_sample_count)) { 
miaux_add_diffuse_component(&sum, dot_nl, diffuse, &light_color) ; 
miaux_add_blinn_specular_component ( 
&sum, state, avg_microfacet_slope, index_of_refraction, 
direction_toward_light, specular, &light_color) ; 
t 
if (light_sample_count) 
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miaux_add_scaled_color(result, &sum, 1.0/light_sample_count) ; 


} 
return miTRUE; 
t 
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declare shader 
color "cook_torrance" ( 
color "ambient" default 
color "diffuse" default 
color "specular" default 
scalar "average_microfacet_slope" default 


color "index_of_refraction" default 
array light "lights" ) 
version 1 
apply material 
end declare 


#include "shader.h" 
#include "miaux.h" 


struct cook_torrance { 
miColor ambient; 
miColor diffuse; 
miColor specular; 
miScalar avg_microfacet_slope; 
miColor index_of_refraction; 
int ye ae 
int n_light ; 
miTag light [1] ; 
ri 


int cook_torrance_version(void) { return 1; } 


miBoolean cook_torrance ( 

miColor *result, miState *state, struct cook_torrance *params  ) 
| 

int i, light_count, light_sample_count; 

miColor sum, light_color; 

miVector direction_toward_light ; 

miscalar dot_nl; 

miTag *light; 


miColor *diffuse = mi_eval_color(&params->diffuse) ; 

miColor *specular = mi_eval_color(&params->specular) ; 

miScalar avg_microfacet_slope = *mi_eval_scalar (&params->avg_microfacet_slope) ; 
miColor *index_of_refraction = mi_eval_color (&params->index_of_refraction) ; 


miaux_light_array(&light, &light_count, state, 
&params->i_light, &params->n_light, params->light) ; 
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*xresult = *mi_eval_color(&params->ambient) ; 


for (i = 0; i < light_count; i++, light++) { 
miaux_set_channels(&sum, 0); 
light_sample_count = 0; 
while (mi_sample_light(&light_color, &direction_toward_light, &dot_nl, 
state, *light, &light_sample_count)) f 
miaux_add_diffuse_component(&sum, dot_nl, diffuse, &light_color) ; 
miaux_add_cook_torrance_specular_component ( 
&sum, state, avg_microfacet_slope, index_of_refraction, 
direction_toward_light, specular, &light_color) ; 
F 
if (light_sample_count) 
miaux_add_scaled_color(result, &sum, 1.0/light_sample_count) ; 


t 
return miTRUE; 
} 
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declare shader 
color "ward" ( 
color "ambient" default 
color "diffuse" default 
color "glossy" default 


scalar "shiny_u_coeff" default 
scalar "shiny_v_coeff" default 
array light "lights" ) 
version 1 
apply material 
end declare 


#include "shader.h" 
#include "miaux.h" 


struct ward { 
miColor ambient; 
miColor diffuse; 
miColor glossy; 
miScalar shiny_u_coeff; 
miScalar shiny_v_coeff; 
int 1 LA et 5 
int n_light ; 
miTag light [1] ; 

}; 


int ward_version(void) { return 1; } 


miBoolean ward ( 
miColor *result, miState *state, struct ward *params  ) 
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{ 
int i, light_count, light_sample_count ; 
miColor sum, light_color; 
miVector direction_toward_light ; 
miScalar dot_nl; 
miTag* light; 
miColor *diffuse = mi_eval_color(&params->diffuse) ; 
miColor *glossy = mi_eval_color(&params->glossy) ; 
miScalar shiny_u_coeff = *mi_eval_scalar (&params->shiny_u_coeff) ; 
miScalar shiny_v_coeff = *mi_eval_scalar(&params->shiny_v_coeff) ; 
miaux_light_array(&light, &light_count, state, 
&params->i_light, &params->n_light, params->light) ; 
*xresult = *mi_eval_color(&params->ambient) ; 
for (i = 0; i < light_count; it+, light++) { 
miaux_set_channels(&sum, 0); 
light_sample_count = 0; 
while (mi_sample_light(&light_color, &direction_toward_light, &dot_nl, 
state, *light, &light_sample_count)) { 
miaux_add_diffuse_component(&sum, dot_nl, diffuse, &light_color) ; 
miaux_add_ward_specular_component ( 
&sum, state, shiny_u_coeff, shiny_v_coeff, glossy, dot_nl, 
direction_toward_light, &light_color) ; 
t 
if (light_sample_count) 
miaux_add_scaled_color(result, &sum, 1.0/light_sample_count) ; 
t 
return miTRUE; 
t 
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declare shader 
color "mock_specular" ( 
color "ambient" default 
color "diffuse" default 
color "specular" default 


color “ewtorr” default 
array light "lights" ) 
version 1 
apply material 
end declare 


#include "shader.h" 
#include "miaux.h" 


struct mock_specular { 
miColor ambient; 
miColor diffuse; 
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miColor specular; 

miColor cutoff; 

int i_light ; 

int n_light ; 

miTag light[1]; 
}; 


int mock_specular_version(void) { return 1; } 


miBoolean mock_specular ( 

miColor *result, miState *state, struct mock_specular *params ) 
: 

int i, light_count, light_sample_count ; 

miColor sum, light_color; 

miVector direction_toward_light ; 

miScalar dot_nl; 

miTag *light; 


miColor *diffuse = mi_eval_color(&params->diffuse) ; 
miColor *specular = mi_eval_color(&params->specular) ; 
miColor *cutoff = mi_eval_color(&params->cutoff) ; 
miaux_light_array(&light, &light_count, state, 

&params->i_light, &params->n_light, params->light) ; 
*xresult = *mi_eval_color(&params->ambient) ; 


for (i = 0; i < light_count; i++, light++) { 
miaux_set_channels(&sum, 0); 
light_sample_count = 0; 
while (mi_sample_light(&light_color, &direction_toward_light, 
&dot_nl, state, *light, &light_sample_count)) { 
miaux_add_diffuse_component(&sum, dot_nl, diffuse, &light_color) ; 
miaux_add_mock_specular_component ( 
&sum, state, &direction_toward_light, 
specular, cutoff, &light_color) ; 
fr 
if (light_sample_count) 
miaux_add_scaled_color(result, &sum, 1/light_sample_count) ; 
} 


return miTRUE; 
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declare shader 
color "rim_bright" ( 
color "ambient" default 0O 
color "diffuse" default 1 
1 


color “rim” default 
array light "lights" ) 
version 1 
apply material 
end declare 


#include "shader.h" 
#include "miaux.h" 


struct rim_bright { 
miColor ambient; 
miColor diffuse; 
miColor rim; 
int i_light ; 
int n_light ; 
miTag light[1i]; 

i 


int rim_bright_version(void) { return 1; } 


miBoolean rim_bright ( 

miColor *result, miState *state, struct rim_bright *params  ) 
{ 

int i, light_count, light_sample_count; 

miColor sum, light_color; 

miVector direction_toward_light ; 

miScalar dot_nl; 

miTag *light; 


miColor *diffuse = mi_eval_color(&params->diffuse) ; 
miColor *rim = mi_eval_color(&params->rim) ; 
miaux_light_array(&light, &light_count, state, 
&params->i_light, &params->n_light, params->light) ; 
*xresult = *mi_eval_color(xparams->ambient) ; 


for (i = 0; i < light cout) if, Light++) + 
miaux_set_channels(&sum, 0); 
light_sample_count = 0; 
while (mi_sample_light(&light_color, &direction_toward_light, 
&dot_nl, state, *light, &light_sample_count) ) 
miaux_add_diffuse_component(&sum, dot_nl, diffuse, &light_color) ; 
if (light_sample_count) { 
miaux_add_scaled_color(result, &sum, 1/light_sample_count) ; 
li 
} 
miaux_brighten_rim(result, state, rim); 
return miTRUE; 
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declare shader 
color "shadow_default" () 


version 1 
apply shadow 
end declare 


#include "shader.h" 
int shadow_default_version(void) { return 1; } 


miBoolean shadow_default ( 
miColor *result, miState *state, void *params ) 


{ 
result->r = result->g = result->b = 0.0; 
return miFALSE; 
} 
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declare shader 
color "shadow _color" ( 
color "color" default 1 i i, 


color "transparency" default .5 .5 .5 ) 
version 1 
apply shadow 
end declare 


/* 
This is an incorrect calculation of the shadow color -- you can’t 
just multiply the original light color by the transparency and 
surface colors. 


*/ 


#include "shader.h" 
#include "miaux.h" 


int shadow_color_version(void) { return 1; } 


struct shadow_color { 
miColor color; 
miColor transparency; 


3 


miBoolean shadow_color ( 
miColor *result, miState *state, struct shadow_color *params ) 


{ 
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miColor *color = mi_eval_color(&params->color) ; 
miColor *transparency = mi_eval_color(&params->transparency) ; 


result->r *= color->r * transparency->r; 
result->g *= color->g * transparency->g; 


result->b *= color->b * transparency->b; 


return miaux_all_channels_equal(result, 0.0) ? miFALSE : miTRUE; 


t 
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declare shader 
color "shadow_breakpoint" ( 
color "color" default ii 1, 
color "transparency" default .5 .5 .5, 


scalar "breakpoint" default .5 ) 
version 1 
apply shadow 
end declare 


#include "shader.h" 
#include "miaux.h" 


int shadow_breakpoint_version(void) { return 1; } 


struct shadow_breakpoint { 
miColor color; 
miColor transparency ; 
miScalar breakpoint; 


¥; 


miBoolean shadow_breakpoint ( 
miColor *result, miState *state, struct shadow_breakpoint *params ) 


{ 
miColor *color = mi_eval_color(&params->color) ; 
miColor *transparency = mi_eval_color(&params->transparency) ; 
miScalar breakpoint = *mi_eval_scalar(&params->breakpoint) ; 
result->r *= miaux_shadow_breakpoint (color->r, transparency->r, breakpoint ); 
result->g *= miaux_shadow_breakpoint (color->g, transparency->g, breakpoint ); 
result->b *= miaux_shadow_breakpoint (color->b, transparency->b, breakpoint ); 
return miaux_all_channels_equal(result, 0.0) ? miFALSE : miTRUE; 
t 
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declare shader 
color "shadow_breakpoint_scale" ( 
color “color” default 1 i1 i, 
color "transparency" default .5 .5 .5, 
scalar "breakpoint" default .5, 


scalar "center" default .5, 
scalar "extent" default 1 ) 
version 1 
apply shadow 
end declare 


#include "shader.h" 
#include "miaux.h" 


int shadow_breakpoint_scale_version(void) { return 1; } 


struct shadow_breakpoint_scale { 
miColor color; 
miColor transparency ; 
miScalar breakpoint ; 
miScalar center; 
miScalar extent; 


re 


miBoolean shadow_breakpoint_scale ( 
miColor *result, miState *state, struct shadow_breakpoint_scale *params  ) 


sf 
miColor *color = mi_eval_color(&params->color) ; 
miColor *transparency = mi_eval_color(&params->transparency) ; 
miScalar breakpoint = *mi_eval_scalar(&params->breakpoint) ; 
miScalar center = *mi_eval_scalar(&params->center) ; 
miScalar extent = *mi_eval_scalar (xparams->extent) ; 
result->r *= miaux_shadow_breakpoint_scale (color->r, transparency->r, 
breakpoint, center, extent ): 
result->g *= miaux_shadow_breakpoint_scale (color->g, transparency->g, 
breakpoint, center, extent )? 
result->b *= miaux_shadow_breakpoint_scale (color->b, transparency->b, 
breakpoint, center, extent ); 
return miaux_all_channels_equal(result, 0.0) ? miFALSE : miTRUE; 
} 
Function Page 
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shadow_continuous Page 178 


declare shader 
color "shadow_continuous" ( 
color "color" default 11 1, 
color "transparency" default .5 .5 .5, 


scalar "expansion" default 1 ) 
version 1 
apply shadow 
end declare 


#include "shader.h" 
#include "miaux.h" 


int shadow_continuous_version(void) { return 1; } 


struct shadow_continuous { 
miColor color; 
miColor transparency ; 
miScalar expansion; 


y: 


miBoolean shadow_continuous ( 
miColor *result, 
miState *state, 
struct shadow_continuous *params  ) 


{ 
miColor *color = mi_eval_color(&params->color) ; 
miColor *transparency = mi_eval_color(&params->transparency) ; 
miScalar expansion = *mi_eval_scalar(&params->expansion) ; 
result->r *= miaux_shadow_continuous (color->r, transparency->r, expansion ); 
result->g *= miaux_shadow_continuous (color->g, transparency->g, expansion ); 
result->b *= miaux_shadow_continuous (color->b, transparency->b, expansion ); 
return miaux_all_channels_equal(result, 0.0) ? miFALSE : miTRUE; 
} 
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declare shader 
color "transparent_shadow" ( 
color “color”, 
color "transparency", 
scalar "breakpoint", 


scalar "center", 
scalar "extent" ) 
version 1 
apply material, shadow 
end declare 


512 B Shader source code 


#include "shader.h" 
#include "miaux.h" 


struct transparent_shadow { 
miColor color; 
miColor transparency; 
miScalar breakpoint; 
miScalar center; 
miScalar extent; 


}; 
int transparent_shadow_version(void) { return(1); } 


miBoolean transparent_shadow ( 
miColor *result, miState *state, struct transparent_shadow *params ) 
{ 


miColor *transparency = mi_eval_color(&params->transparency) ; 


if (state->type == miRAY_SHADOW) { 
miColor *color = mi_eval_color(&params->color) ; 
miScalar breakpoint = *mi_eval_scalar(&params->breakpoint) ; 
miScalar center = *mi_eval_scalar(&params->center) ; 
miScalar extent = *mi_eval_scalar(&params->extent) ; 


result->r *= miaux_shadow_breakpoint_scale(color->r, transparency->r, 
breakpoint, center, extent); 
result->g *= miaux_shadow_breakpoint_scale(color->g, transparency->g, 
breakpoint, center, extent); 
result->b *= miaux_shadow_breakpoint_scale(color->b, transparency->b, 
breakpoint, center, extent); 
return miaux_all_channels_equal(result, 0.0) ? miFALSE : miTRUE; 
} 
if (miaux_all_channels_equal(transparency, 0.0)) 
*xresult = *mi_eval_color(&params->color) ; 
else { 
mi_trace_transparent (result, state); 
if (!miaux_all_channels_equal(transparency, 1.0)) { 
miColor *color = mi_eval_color(&params->color) ; 
miColor opacity; 
miaux_invert_channels(opacity, transparency) ; 
mi_opacity_set(state, opacity) ; 
miaux_blend_channels(result, color, transparency) ; 
} 
} 
return miTRUE; 
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specular reflection Page 184 


declare shader 
color "specular_reflection" () 


version 1 
apply material 
end declare 


#include "shader.h" 
int specular_reflection_version(void) { return 1; } 


miBoolean specular_reflection ( 
miColor *result, miState *state, void *params ) 


{ 
miVector reflection_direction; 
mi_reflection_dir(&reflection_direction, state); 
if (!mi_trace_reflection(result, state, &reflection_direction) ) 
mi_trace_environment(result, state, &reflection_direction) ; 
return miTRUE; 
} 
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declare shader 
color "glossy_reflection" ( 
scalar "shiny" default 5 ) 


version 1 
apply material 
end declare 


#include "shader.h" 


struct glossy_reflection { 
miScalar shiny; 


¥3 
int glossy_reflection_version(void) { return 1; } 


miBoolean glossy_reflection ( 
miColor *result, miState *state, struct glossy_reflection *params ) 
{ 
miVector reflection_dir; 
miScalar shiny = *mi_eval_scalar(&params->shiny) ; 
mi_reflection_dir_glossy(&reflection_dir, state, shiny); 


if ('mi_trace_reflection(result, state, &kreflection_dir) ) 
mi_trace_environment(result, state, &reflection_dir) ; 


return miTRUE; 
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declare shader 
color "glossy_reflection_sample" ( 
scalar "Shiny" default 5, 


integer "samples" default 8 ) 
version 1 
apply material 
end declare 


#include "shader.h" 
#include "miaux.h" 


struct glossy_reflection_sample { 
miScalar shiny; 
milnteger samples; 


; 


int glossy_reflection_sample_version(void) { return 1; } 


miBoolean glossy_reflection_sample ( 
miColor *result, miState *state, struct glossy_reflection_sample *params  ) 


1. 
miScalar shiny = *mi_eval_scalar(&params->shiny) ; 
miUint samples = *mi_eval_integer(&params->samples) ; 
miVector reflect_dir; 
miColor reflect_color; 
int sample_number = 0; 
double sampled_dir[2] ; 
result->r = result->g = result->b = 0.0; 
while (mi_sample(sampled_dir, &sample_number, state, 2, &samples)) { 
mi_reflection_dir_glossy_x(&reflect_dir, state, shiny, sampled_dir) ; 
if (!mi_trace_reflection(&reflect_color, state, &reflect_dir) ) 
mi_trace_environment (&reflect_color, state, &reflect_dir) ; 
miaux_add_color(result, kreflect_color) ; 
} 
miaux_scale_color(result, 1.0 / (double)samples) ; 
return miTRUE; 
} 
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declare shader 
color "glossy_reflection_sample_varying" ( 
scalar "shiny" default 5, 


array integer "samples" ) 
version 1 
apply material 
end declare 
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#include "shader.h" 
#include "miaux.h" 


struct glossy_reflection_sample_varying { 
miScalar shiny; 
int i_samples; 
int n_samples; 
int samples[1]; 
}; 


int glossy_reflection_sample_varying_version(void) { return 1; } 


miBoolean glossy_reflection_sample_varying ( 
miColor *result, miState *state, 
struct glossy_reflection_sample_varying *params ) 


miScalar shiny = *mi_eval_scalar(&params->shiny) ; 

int i_samples = *mi_eval_integer(&params->i_samples) ; 

int n_samples = *mi_eval_integer(&params->n_samples) ; 

int *samples = mi_eval_integer(params->samples) + i_samples; 

miVector reflect_dir; 

miColor reflect_color; 

double sampled_dir [2] ; 

int level = state->reflection_level, sample_number = 0; 

miUint sample_count = samples[level >= n_samples ? n_samples - 1 : level]; 


if (sample_count == 1) { 
mi_reflection_dir_glossy(&reflect_dir, state, shiny); 
if (!mi_trace_reflection(result, state, &reflect_dir)) 
mi_trace_environment (result, state, &reflect_dir) ; 
+ else { 
result->r = result->g = result->b = 0.0; 
while (mi_sample(sampled_dir, &sample_number, 
state, 2, &sample_count)) { 
mi_reflection_dir_glossy_x(&reflect_dir, state, shiny, 
sampled_dir) ; 
if (!mi_trace_reflection(kreflect_color, state, &reflect_dir)) 
mi_trace_environment (&reflect_color, state, &reflect_dir); 
miaux_add_color(result, kreflect_color) ; 
} 
miaux_scale_color(result, 1.0 / (double)sample_count) ; 
} 
return miTRUE; 


Function Page 
miaux_add_color 593 
miaux_scale_color 592 
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declare shader 
color "specular_refraction_simple" ( 
scalar "index_of_refraction" default 1.33 ) 


version 1 
apply material 
end declare 
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#include "shader.h" 
#include "miaux.h" 


struct specular_refraction_simple { 
miScalar index_of_refraction; 


}; 
int specular_refraction_simple_version(void) { return 1; } 


miBoolean specular_refraction_simple ( 
miColor *result, miState *state, struct specular_refraction_simple *params ) 


{ 
miScalar instance_ior = *mi_eval_scalar (&params->index_of_refraction) ; 
miScalar vacuum_ior = 1.0, incoming_ior, outgoing_ior; 
miVector direction; 
if (miaux_ray_is_entering_material(state)) { 
incoming_ior = vacuum_ior; 
outgoing ior = instance_ior; 
} else { 
incoming _ior = instance_ior; 
outgoing _ior = vacuum_ior; 
7 
if (mi_refraction_dir(&direction, state, incoming_ior, outgoing_ior)) 
mi_trace_refraction(result, state, &direction) ; 
else { 
mi_reflection_dir(&direction, state); 
if (!mi_trace_reflection(result, state, &direction) ) 
mi_trace_environment(result, state, &direction) ; 
} 
return miTRUE; 
} 
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declare shader 
color "specular_refraction" ( 
scalar "index_of_refraction" default 1.33 ) 


version 1 
apply material 
end declare 


#include "shader.h" 
#include "miaux.h" 


struct specular_refraction { 
miScalar index_of_refraction; 


}; 
int specular_refraction_version(void) { return 1; } 


miBoolean specular_refraction ( 
miColor *result, miState *state, struct specular_refraction *params ) 
{ 


miVector direction; 
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miScalar ior = *mi_eval_scalar(&params->index_of_refraction) ; 
miaux_set_state_refraction_indices(state, ior); 


if (mi_refraction_dir(&direction, state, state->ior_in, state->ior) ) 
mi_trace_refraction(result, state, &direction) ; 
else { 
mi_reflection_dir(&direction, state); 
if (!mi_trace_reflection(result, state, &direction) ) 
mi_trace_environment (result, state, &direction) ; 


i 
return miTRUE; 
t 
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declare shader 
color "glossy_refraction" ( 
scalar "index_of_refraction" defaul 
scalar "shiny" default 5 ) 


version 1 
apply material 
end declare 


#include "shader.h" 
#include "miaux.h" 


struct glossy_refraction { 
miScalar index_of_refraction; 
miScalar shiny; 


}; 
int glossy_refraction_version(void) { return 1; } 


miBoolean glossy_refraction ( 
miColor *result, miState *state, struct glossy_refraction *params ) 
{ 
miVector direction; 
miScalar ior = *mi_eval_scalar (&params->index_of_refraction) ; 
miScalar shiny = *mi_eval_scalar(&params->shiny) ; 


miaux_set_state_refraction_indices(state, ior); 


if (mi_transmission_dir_glossy(&direction, state, 
state->ior_in, state->ior, shiny) ) 
mi_trace_refraction(result, state, &direction) ; 
else { 
mi_reflection_dir(&direction, state); 
if (!'mi_trace_reflection(result, state, &kdirection) ) 
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mi_trace_environment (result, state, &direction) ; 


} 
return miTRUE; 
} 
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declare shader 
color "glossy_refraction_sample" ( 
scalar "index_of_refraction" default 1.33, 
scalar "shiny" default 50, 


integer "samples" default 8 ) 
version 1 
apply material 
end declare 


#include "shader.h" 
#include "miaux.h" 


struct glossy_refraction_sample { 
miScalar index_of_refraction; 
miScalar shiny; 
miInteger samples; 


ti 
int glossy_refraction_sample_version(void) { return 1; } 


miBoolean glossy_refraction_sample ( 

miColor *result, miState *state, struct glossy_refraction_sample *params ) 
{ 

miScalar ior = *mi_eval_scalar (&params->index_of_refraction) ; 

miScalar shiny = *mi_eval_scalar(&params->shiny) ; 

miUint samples = *mi_eval_integer(params->samples) ; 

miVector refract_dir, reflect_dir; 

miColor refract_color; 

int sample_number = 0; 

double sample[2]; 


miaux_set_state_refraction_indices(state, ior); 


result->r = result->g = result->b = 0.0; 
while (mi_sample(sample, &sample_number, state, 2, &samples)) { 
if (mi_transmission_dir_glossy_x(krefract_dir, state, 
Sstate->ior_in, state->ior, 
shiny, sample)) { 
if (mi_trace_refraction(krefract_color, state, krefract_dir)) 
miaux_add_color(result, &refract_color) ; 
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else { 
mi_reflection_dir(&reflect_dir, state); 
if ('mi_trace_reflection(&refract_color, state, &reflect_dir)) 
mi_trace_environment (&refract_color, state, &reflect_dir) ; 
miaux_add_color(result, &refract_color) ; 
} 
} 
miaux_scale_color(result, 1.0 / samples); 
return miTRUE; 


t 
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declare shader 
color "glossy_refraction_sample_varying" ( 
scalar "“index_of_refraction" default 1.33, 
scalar "shiny" default 50, 


array integer "samples" ) 
version 1 
apply material 
end declare 


#include "shader.h" 
#include "miaux.h" 


struct glossy_refraction_sample_varying { 
miScalar index_of_refraction; 
miScalar shiny; 
int i_samples; 
int n_samples; 
int samples[1]; 

}; 


int glossy_refraction_sample_varying_version(void) { return 1; } 
miBoolean glossy_refraction_sample_varying ( 


miColor *result, miState *state, 
struct glossy_refraction_sample_varying *params ) 


{ 
miScalar ior = *mi_eval_scalar(&params->index_of_refraction) ; 
miScalar shiny = *mi_eval_scalar(&params->shiny) ; 
int i_samples = *mi_eval_integer(xparams->i_samples) ; 
int n_samples = *mi_eval_integer(&params->n_samples) ; 
int *samples = mi_eval_integer(params->samples) + i_samples; 


miVector refraction_dir, reflect_dir; 
miColor refract_color, reflect_color; 
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int sample_number = 0; 
double sample[2] ; 
miUint sample_count ; 


sample_count = samples[state->refraction_level >= n_samples ? 
n_samples - 1 
state->refraction_level]; 


miaux_set_state_refraction_indices(state, ior); 


if (sample_count == 1) { 
if (mi_transmission_dir_glossy(&refraction_dir, state, 
state->ior_in, state->ior, shiny)) 
mi_trace_refraction(result, state, &refraction_dir) ; 
else { 
mi_reflection_dir(&reflect_dir, state); 
if (!mi_trace_reflection(result, state, &reflect_dir) ) 
mi_trace_environment(result, state, &reflect_dir); 
} 
+ else { 
result->r = result->g = result->b = 0.0; 
while (mi_sample(sample, &sample_number, state, 2, &sample_count)) { 
if (mi_transmission_dir_glossy_x(&refraction_dir, state, 
state->ior_in, state->ior, 
shiny, sample)) { 
if (mi_trace_refraction(&refract_color, state, krefraction_dir) ) 
miaux_add_color(result, &refract_color) ; 


5 
else { 
mi_reflection_dir(&reflect_dir, state); 
if (!mi_trace_reflection(&reflect_color, state, &reflect_dir)) 
mi_trace_environment (&reflect_color, state, &reflect_dir); 
miaux_add_color(result, &reflect_color) ; 
} 
iy 
miaux_scale_color(result, 1.0 / sample_count) ; 
} 
return miTRUE; 
} 
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op mix_ccc Page 212 


declare shader 
color "op_mix_ccc" ( 
color “A”, 
color “Bb”; 


color "F" ) 
version 1 
apply material 
end declare 


#include "shader.h" 
#include "miaux.h" 


int op_mix_ccc_version(void) { return 1; } 


Struct op.mix cec + 
miColor A; 
miColor B; 
miColor F; 


es 


miBoolean op_mix_ccc (miColor *result, miState *state, struct op_mix_ccc *params ) 


{ 


miColor *A = mi_eval_color(&params->A) ; 
miColor *B = mi_eval_color(&params->B) ; 
miColor *F = mi_eval_color(&params->F) ; 
result->r = miaux_blend(A->r, B->r, F->r); 
result->g = miaux_blend(A->g, B->g, F->g); 
result->b = miaux_blend(A->b, B->b, F->b); 
return miTRUE; 


t 
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declare shader 
color "op_pow_cs" ( 
colar "a", 


scalar "B" ) 
version 1 
apply material 
end declare 


#include "shader.h" 
#include "math.h" 


int op_pow_cs_version(void) { return 1; } 


struct op_pow_cs { 
miColor A; 
miScalar B; 


Fi 
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miBoolean op_pow_cs (miColor *result, miState *state, struct op_pow_cs *params ) 


| 


miColor *A = mi_eval_color(&params->A) ; 
miScalar B = *mi_eval_scalar(&params->B) ; 
result->r = powf(A->r, B); 

result->g = powf(A->g, B); 

result->b = powf(A->b, B); 

return miTRUE; 
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declare shader 
color "global_lambert" ( 
color "ambient" default O O 0, 
1 


color "diffuse" default 1 1 1, 


array light "lights" ) 
version 1 
apply material 
end declare 


#include "shader.h" 
#include "miaux.h" 


struct global_lambert { 
miColor ambient; 
miColor diffuse; 
int i_light ; 
int n_light; 
miTag light[1]; 
}; 


int global_lambert_version(void) { return 1; } 


miBoolean global_lambert ( 

miColor *result, miState *state, struct global_lambert *params ) 
| 

int 1, light_count, light_sample_count ; 

miColor sum, light_color, global_illumination_color; 

miScalar dot_nl; 

miTag *light; 


miColor *diffuse = mi_eval_color(&params->diffuse) ; 
miaux_light_array(&light, &light_count, state, 

&params->i_light, &params->n_light, params->light) ; 
*xresult = *mi_eval_color(&params-—>ambient) ; 


for (i = 0; i < light_count; i++, light++) { 
miaux_set_channels(&sum, 0); 
light_sample_count = 0; 
while (mi_sample_light(&light_color, NULL, &dot_nl, 
state, *light, &light_sample_count) ) 
miaux_add_diffuse_component(&sum, dot_nl, diffuse, &light_color) ; 
if (light_sample_count) 
miaux_add_scaled_color(result, &sum, 1.0/light_sample_count) ; 
I 


mi_compute_avg_radiance(&global_illumination_color, state, ’f’, NULL); 
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miaux_add_multiplied_colors(result, &global_illumination_color, diffuse) ; 
result->a = 1.0; 


return miTRUE; 


} 
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declare shader 
color "store_diffuse_photon" ( 
color "diffuse_color" default 111 ) 


version 1 
apply photon 
end declare 


#include "shader.h" 
#include "miaux.h" 


struct store_diffuse_photon { 
miColor diffuse_color; 


rs 
int store_diffuse_photon_version(void) { return 1; } 


miBoolean store_diffuse_photon ( 
miColor *result, miState *state, struct store_diffuse_photon *params  ) 


{ 
miVector diffuse_direction; 
miColor *diffuse_color = mi_eval_color(&params->diffuse_color) ; 
mi_store_photon(result, state); 
miaux_multiply_color(result, diffuse_color) ; 
mi_reflection_dir_diffuse(&diffuse_direction, state); 
return mi_photon_reflection_diffuse(result, state, &diffuse_direction) ; 
t 
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declare shader 
color "average_radiance" ( 
color "color" default 111 ) 


version 1 
apply material 
end declare 
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#include "shader.h" 
#include "miaux.h" 


int average_radiance_version(void) { return 1; } 
struct average_radiance { 
miColor color; 


¥;3 


miBoolean average_radiance ( 
miColor *result, miState *state, struct average_radiance *params  ) 


{ 
miColor *color = mi_eval_color(&params->color) ; 
mi_compute_avg_radiance(result, state, ’f’, NULL); 
miaux_multiply_color(result, color); 
return miTRUE; 
t 
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declare shader 
color "average_radiance_options" ( 
color "color" default 
integer "globillum_accuracy" default -1, 
scalar "globillum_radius" default -1.0, 
integer "finalgather_rays" default -1, 
scalar "finalgather_maxradius" default -1.0, 
scalar "finalgather_minradius" default 
integer "finalgather_view" default 
integer "finalgather_filter" default 
integer "finalgather_points" default 
scalar "importance" default 
integer "caustic_accuracy" default 
scalar "caustic_radius" default 
version 1 
end declare 


#include "shader.h" 
#include "miaux.h" 


int average_radiance_options_version(void) { return 1; } 


struct average_radiance_options { 
miColor colors 
miInteger gi_accuracy; 
miScalar gi_radius; 
milnteger fg_rays; 
miScalar fg_maxradius; 
miScalar fg_minradius; 
miinteger fg_view; 
miInteger fg_filter; 
miInteger fg_points; 
miScalar importance; 
milnteger caustic_accuracy; 
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miScalar caustic_radius; 


rj 


miBoolean average_radiance_options ( 

miColor *result, miState *state, struct average_radiance_options *params  ) 
{ 

miColor *color = mi_eval_color(&params->color) ; 

milrrad_options options; 

miIRRAD_DEFAULT(&options, state) ; 


miaux_set_integer_if_not_default ( 

&options.globillum_accuracy, state, &params->gi_accuracy) ; 
miaux_set_scalar_if_not_default( 

&options.globillum_radius, state, &params->gi_radius) ; 
miaux_set_integer_if_not_default ( 

&options.finalgather_rays, state, &params->fg_rays) ; 
miaux_set_scalar_if_not_default ( 

&options.finalgather_maxradius, state, &params->fg_maxradius) ; 
miaux_set_scalar_if_not_default ( 

&options.finalgather_minradius, state, &params->fg_minradius) ; 
miaux_set_integer_if_not_default ( 

(miInteger*)options.finalgather_view, state, &params->fg_view); 
miaux_set_integer_if_not_default ( 

(miInteger*)options.finalgather_filter, state, &params->fg_filter) ; 
miaux_set_integer_if_not_default ( 

(milnteger*)koptions.finalgather_points, state, &params->fg_points) ; 
miaux_set_scalar_if_not_default ( 

&options.importance, state, &params->importance) ; 
miaux_set_integer_if_not_default ( 

&options.caustic_accuracy, state, &params->caustic_accuracy) ; 
miaux_set_scalar_if_not_default ( 

&options.caustic_radius, state, &params->caustic_radius) ; 


mi_compute_avg_radiance(result, state, ’f’, &options); 
miaux_multiply_color(result, color); 


return miTRUE; 
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declare shader 
color "transmit_specular_photon" ( 
color "transparency" default 1 1 1, 


scalar "index_of_refraction" default 1.33 ) 
version 1 
apply photon 
end declare 


#include "shader.h" 
#include "miaux.h" 
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struct transmit_specular_photon { 
miColor transparency; 
miScalar index_of_refraction; 


}; 
int transmit_specular_photon_version(void) { return 1; } 


miBoolean transmit_specular_photon ( 
miColor *result, miState *state, struct transmit_specular_photon *params  ) 


{ 
miVector photon_direction; 
miColor new_energy; 
miaux_multiply_colors(&new_energy, result, 
mi_eval_color(&params->transparency) ) ; 
mi_refraction_dir(&photon_direction, state, 1.0, 

*mi_eval_scalar (&params->index_of_refraction) ) ; 
mi_photon_transmission_specular(&new_energy, state, &photon_direction) ; 
return miTRUE; 

} 
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declare shader 
color "ambient_occlusion" ( 
integer "samples" default 8 ) 


version 1 
apply material 
end declare 


#include "shader.h" 
#include "miaux.h" 


struct ambient_occlusion { 
miUint samples; 


3 
int ambient_occlusion_version(void) {return(1);} 


miBoolean ambient_occlusion ( 

miColor *result, miState *state, struct ambient_occlusion *params ) 
{ 

miUint samples = *mi_eval_integer(&params->samples) ; 

miVector trace_direction; 

int object_hit = 0, sample_number = 0; 

double sample[2], hit_fraction, ambient_exposure; 


while (mi_sample(sample, &sample_number, state, 2, &samples)) { 
mi_reflection_dir_diffuse_x(&trace_direction, state, sample) ; 
if (mi_trace_probe(state, &trace_direction, &state->point) ) 
object_hit++; 
} 
hit_fraction = ((double)object_hit / (double)samples) ; 
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ambient_exposure = 1.0 - hit_fraction; 
result->r = result->g = result->b = ambient_exposure; 
result->a = 1.0; 


return miTRUE; 
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declare shader 
color "ambient_occlusion_cutoff" ( 
integer "samples" default 8, 


scalar "cutoff_distance" default 1, ) 
version 1 
apply material 
end declare 


#include "shader.h" 
#include "miaux.h" 


struct ambient_occlusion_cutoff { 
miUint samples; 
miScalar cutoff_distance; 


re 
int ambient_occlusion_cutoff_version(void) {return(1) ;} 


miBoolean ambient_occlusion_cutoff ( 

miColor *result, miState *state, struct ambient_occlusion_cutoff *params ) 
{ 

miUint samples = *mi_eval_integer (&params->samples) ; 

miScalar cutoff_distance = *mi_eval_scalar (&params->cutoff_distance) ; 

miVector trace_direction; 

int object_hit = 0, sample_number = 0; 

double sample[2], hit_fraction, ambient_exposure, 

falloff_start, falloff_stop; 


falloff_start = falloff_stop = cutoff_distance; 
mi_ray_falloff(state, &falloff_start, &falloff_stop) ; 


while (mi_sample(sample, &sample_number, state, 2, &samples)) f{ 
mi_reflection_dir_diffuse_x(&trace_direction, state, sample); 
if (mi_trace_probe(state, &trace_direction, &state->point) ) 

object hittt; 

} 

hit_fraction = ((double)object_hit / (double)samples) ; 

ambient_exposure = 1.0 - hit_fraction; 

result->r = result->g = result->b = ambient_exposure; 

result->a 1% 


mi_ray_falloff(state, &falloff_start, &falloff_stop) ; 
return miTRUE; 
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declare shader 
scalar "displace_wave" ( 
scalar "frequency" default 1, 
scalar "amplitude" default .5 ) 


version 1 
apply displace 
end declare 


#include "shader.h" 
#include "miaux.h" 


struct displace_wave { 
miScalar frequency; 
miScalar amplitude; 


ie 
int displace_wave_version(void) { return(1); } 


miBoolean displace_wave ( 
miScalar *result, miState *state, struct displace_wave *params ) 


{ 
*xresult += miaux_sinusoid(state->point.x, 
*mi_eval_scalar(&params->frequency) , 
*mi_eval_scalar (&params->amplitude) ) ; 
return miTRUE; 
t 
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declare shader 
scalar "displace_wave_uv" ( 
scalar "frequency_u" default 
scalar "amplitude_u" default 


scalar "frequency_v" default 
scalar "amplitude_v" default 
version 1 
apply displace 
end declare 


#include "shader.h" 
#include "miaux.h" 


struct displace_wave_uv { 
miScalar frequency_u; 
miScalar amplitude_u; 
miScalar frequency_v; 
miScalar amplitude_v; 


¥} 


int displace_wave_uv_version(void) { return(1); } 
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miBoolean displace_wave_uv ( 
miScalar *result, miState *state, struct displace_wave_uv *params  ) 


{ 
*result += 
miaux_sinusoid(state->tex_list[0].x, 
*mi_eval_scalar (&params->frequency_u) , 
*mi_eval_scalar(&params->amplitude_u)) + 
miaux_sinusoid(state->tex_list[l0].y, 
*mi_eval_scalar (&params->frequency_v) , 
*mi_eval_scalar (&params->amplitude_v)) ; 
return miTRUE; 
F 
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declare shader 
scalar "displace_ripple" ( 
vector "center" default .5 .5 O, 
scalar "frequency" default 1, 


scalar "amplitude" default .1 ) 
version 1 
apply displace 
end declare 


#include "shader.h" 
#include "miaux.h" 


struct displace_ripple { 
miVector center; 
miScalar frequency; 
miScalar amplitude; 


I; 
int displace_ripple_version(void) { return(1); } 


miBoolean displace_ripple ( 
miScalar *result, miState *state, struct displace_ripple *params ) 


1. 
*xresult += miaux_sinusoid(mi_vector_dist (mi_eval_vector (&params->center) , 
&state->tex_list[0]), 
*mi_eval_scalar(&params->frequency) , 
*mi_eval_scalar (&params->amplitude) ) ; 
return miTRUE; 
} 
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declare shader 
scalar "displace_texture" ( 
color texture "texture", 
scalar "factor" default .1 ) 


version 1 
apply displace 
end declare 


#include "shader.h" 
#include "miaux.h" 


struct displace_texture { 
miTag texture; 
miScalar factor; 


}; 
int displace_texture_version(void) { return(1i); } 


miBoolean displace_texture ( 
miScalar *result, miState *state, struct displace_texture *params ) 


{ 
miCGolor color; 
mi_lookup_color_texture(&color, state, 
*mi_eval_tag(&params->texture) , 
&state->tex_list[0]); 
*xresult += *mi_eval_scalar(&params->factor) * color.r; 
return miTRUE; 
} 
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declare shader 
scalar "summed_noise_scalar" ( 
scalar "point_scale" default 1, 
scalar "magnitude" default 1, 
scalar "octave_scaling" default 2, 


scalar "summing_weight" default 2, 
integer "number_of_octaves" default 5 ) 
version 1 
apply material, texture 
end declare 


#include "shader.h" 
#include "miaux.h" 


struct summed_noise_scalar { 
miScalar point_scale; 
miScalar magnitude; 
miScalar octave_scaling; 
miScalar summing weight; 
miInteger number_of_octaves; 


ie 


int summed_noise_scalar_version(void) { return(1); } 
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miBoolean summed_noise_scalar ( 
miScalar *result, miState *state, struct summed_noise_scalar *params  ) 


+ 
miVector object_point; 
miScalar magnitude = *mi_eval_scalar(&params->magnitude), noise_sum; 
mi_point_to_object(state, &object_point, &state->point) ; 
mi_vector_mul(&object_point, *mi_eval_scalar (&params->point_scale) ) ; 
noise_sum = miaux_summed_noise(&object_point, 
*mi_eval_scalar (&params->summing_weight) , 
*mi_eval_scalar (&params->octave_scaling) , 
*mi_eval_integer (&params->number_of_octaves) ) ; 
*xresult += miaux_fit(noise_sum, 0.0, 1.0, -magnitude, magnitude) ; 
return miTRUE; 
} 
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declare shader 
color "bump_wave" ( 
scalar "frequency" default 1, 


scalar "amplitude" default .5 ) 
version 1 
apply material 
end declare 


#include "shader.h" 
#include "miaux.h" 


struct bump_wave { 
miScalar frequency; 
miScalar amplitude; 


}; 
int bump_wave_version(void) { return(1); } 


miBoolean bump_wave ( 
miColor *result, miState *state, struct bump_wave *params ) 
{ 
state->normal.x += miaux_sinusoid(state->point.x, 
*mi_eval_scalar (&params->frequency) , 
*mi_eval_scalar (&params->amplitude) ) ; 
mi_vector_normalize(&state->normal) ; 
return miTRUE; 


532 B Shader source code 
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declare shader 
color "bump_wave_uv" ( 
scalar "frequency_u" default 
scalar "amplitude_u" default 


scalar "frequency_v" default 
scalar "amplitude_v" default 
version 1 
apply material 
end declare 


#include "shader.h" 
#include "miaux.h" 


struct bump_wave_uv { 
miScalar frequency_u; 
miScalar amplitude_u; 
miScalar frequency_v; 
miScalar amplitude_v; 


}; 
int bump_wave_uv_version(void) { return(1); } 


miBoolean bump_wave_uv ( 
miColor *result, miState *state, struct bump_wave_uv *params ) 


if 
state->normal.x += miaux_sinusoid(state->tex_list[0].x, 
*mi_eval_scalar(&params->frequency_u) , 
*mi_eval_scalar (&params->amplitude_uw) ) ; 
state->normal.y += miaux_sinusoid(state->tex_list[0].y, 
*mi_eval_scalar (&params->frequency_v) , 
*mi_eval_scalar(xparams->amplitude_v)) ; 
mi_vector_normalize(&state->normal) ; 
return miTRUE; 
} 
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declare shader 
color "bump_ripple" ( 
vector "center" default 
scalar "frequency" default 
scalar "amplitude" default 


scalar "nearby" default 
version 1 
apply material 
end declare 


bump_ripple 


#include "shader.h" 
#include "miaux.h" 


struct bump_ripple { 
miVector center; 
miScalar frequency; 
miScalar amplitude; 
miScalar nearby; 


}; 
int bump_ripple_version(void) { return(1); } 


miBoolean bump_ripple ( 
miColor *result, miState *state, struct bump_ripple *params  ) 
{ 
double ripple_here, ripple_over, ripple_up, 
change_going_over, change_going_up; 
miVector here, over, up; 


miVector center = *mi_eval_vector(params->center) ; 
miScalar frequency = *mi_eval_scalar(&params->frequency) ; 
miScalar amplitude = *mi_eval_scalar(&params->amplitude) ; 
miScalar nearby = *mi_eval_scalar (&params->nearby) ; 


miVector bump_basis_u = state->bump_x_list [0]; 
miVector bump_basis_v = state->bump_y_list [0]; 


here = state->tex_list [0] ; 
miaux_set_vector(&over, here.x + nearby, here.y, here.z); 
miaux_set_vector(kup, here.x, here.y + nearby, here.z); 


ripple_here = miaux_sinusoid(mi_vector_dist(&center, &here), 
frequency, amplitude) ; 
miaux_sinusoid(mi_vector_dist(&kcenter, &over), 
frequency, amplitude) ; 
ripple_up = miaux_sinusoid(mi_vector_dist(&center, &up), 
frequency, amplitude) ; 


ripple_over 


change_going_over = ripple_over - ripple_here; 
change_going_up = ripple_over - ripple_up; 


mi_vector_mul(&bump_basis_u, -change_going_over) ; 
mi_vector_mul(&bump_basis_v, -change_going_up) ; 


mi_vector_to_object(state, &state->normal, &state->normal) ; 
mi_vector_add(&state->normal, &state->normal, &bump_basis_u) ; 
mi_vector_add(&state->normal, &state->normal, &bump_basis_v) ; 
mi_vector_normalize(&state->normal) ; 
mi_vector_from_object(state, &state->normal, &state->normal) ; 


return miTRUE; 
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declare shader 
color "bump_texture" ( 
color texture "texture", 
scalar "factor" default 1, 


scalar "nearby" default .001 ) 
version 1 
apply material 
end declare 


#include "shader.h" 
#include "miaux.h" 


struct bump_texture { 
miTag texture; 
miScalar factor; 
miScalar nearby; 


i 
int bump_texture_version(void) { return(1); } 


miBoolean bump_texture ( 
miColor *result, miState *state, struct bump_texture *params ) 
7 
miColor color_here, color_over, color_up; 
miScalar value_here, value_over, value_up, 
change_going_over, change_going_up; 
miVector here, over, up; 


miTag texture = *mi_eval_tag(&params->texture) ; 
miScalar factor = *mi_eval_scalar(&params->factor) ; 
miScalar nearby = *mi_eval_scalar(&params->nearby) ; 


miVector bump_basis_u 
miVector bump_basis_v 


state->bump_x_list [0] ; 
state->bump_y_list [0]; 


here = state->tex_list[0]; 
miaux_set_vector(xover, here.x + nearby, here.y, here.z); 
miaux_set_vector(&up, here.x, here.y + nearby, here.z); 


if (!mi_lookup_color_texture(&color_here, state, texture, &here)) 
return miFALSE; 
value_here = miaux_color_channel_average(&color_here) ; 


mi_flush_cache(state) ; 
value_over = mi_lookup_color_texture(&color_over, state, texture, Xover) ? 
miaux_color_channel_average(&color_over) : value_here; 


mi_flush_cache(state) ; 
value_up = mi_lookup_color_texture(&color_up, state, texture, kup) ? 
miaux_color_channel_average(&color_up) : value_here; 


change_going_over = factor * (value_over - value_here) ; 
change_going_up = factor * (value_up - value_here) ; 


mi_vector_mul(&bump_basis_u, -change_going_over) ; 
mi_vector_mul(&bump_basis_v, -change_going_up) ; 
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mi_vector_to_object(state, &state->normal, &state->normal) ; 
mi_vector_add(&state->normal, &state->normal, &bump_basis_u) ; 
mi_vector_add(&state->normal, &state->normal, &bump_basis_v) ; 
mi_vector_normalize(&state->normal]) ; 
mi_vector_from_object(state, &state->normal, &state->normal) ; 


return miTRUE; 


} 
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declare shader 
geometry "square" () 


version 1 
apply geometry 
end declare 


#include "shader.h" 
#include "geoshader.h" 


int square_version(void) { return 1; } 


miBoolean square ( 

miTag *result, miState *state, void *params ) 
{ 

Int i; 

miVector v; 

miTag object_tag; 


/* 1. Begin the object definition. */ 
midbject *obj = mi_api_object_begin(mi_mem_strdup("::square")) ; 


/* 2. Set the object flags. */ 
obj->visible = miTRUE; 
obj->shadow = 3; 


/* 3. Begin the object group definition. */ 
mi_api_object_group_begin(0.0) ; 


/* 4. Define the vectors to be used for vertices. */ 


v.x = -.5; v.y = -.5; v.z = 0; mi_api_vector_xyz_add(&v) ; 
v.x = .5; mi_api_vector_xyz_add (kv) ; 
v.y = .5;  mi_api_vector_xyz_add (kv) ; 
v.x = -.5; mi_api_vector_xyz_add(kv) ; 


/* 5. Define the vectors to be used for normals. */ 
v.x = 0; v.y = 0; v.z = 1; mi_api_vector_xyz_add (kv) ; 


/* 6. Define the vectors to be used for texture coordinates. */ 
v.x = 0; v.y = 0; v.z = 0; mi_api_vector_xyz_add (kv) ; 

= 1; mi_api_vector_xyz_add(&v) ; 

1; mi_api_vector_xyz_add(&v) ; 


g 
rs 
| 


< 
= 
ll 


536 


v.x = 0; mi_api_vector_xyz_add(k&v) ; 


/* 7. Specify the sets of vectors to be used for the position, 
normal and coordinates of each vertex. */ 
for (i = 0; i < 4; i++) { 
mi_api_vertex_add(i) ; 
mi_api_vertex_normal_add(A4) ; 
mi_api_vertex_tex_add(i + 5, -1, -1); 


t 


/* 8. Specify the vertices to be used for each polygon. */ 
mi_api_poly_begin_tag(1, 0); 
for (i = 0; i < 4; i++) 
mi_api_poly_index_add(i) ; 
mi_api_poly_end() ; 


/* 9. End the object group definition. */ 
mi_api_object_group_end() ; 


/* 10. End the object definition. */ 
object_tag = mi_api_object_end() ; 


/* 11. Add the resulting object to the database. */ 
return mi_geoshader_add_result(result, object_tag) ; 


triangles 


declare shader 


geometry "triangles" ( 
string "name", 
integer "count" default 100, 
vector "bbox_min" default -.5 -.5 -.5, 
vector "bbox_max" default .5 .5 .5, 


scalar "edge_length_max" default 1, 
integer "random_seed" default 1955 ) 
version 1 
apply geometry 
end declare 


#include "shader.h" 
#include "geoshader.h" 
#include "miaux.h" 


struct triangles { 


ie 


miTag name; 

miinteger count; 
miVector bbox_min; 
miVector bbox_max; 
miScalar edge_length_max; 
milnteger random_seed; 


int triangles_version(void) { return 1; } 


miBoolean triangles ( 


miTag *result, miState *state, struct triangles *params ) 
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{ 
int vertex_index; 
miQbject *obj; 
miInteger count = *mi_eval_integer(&params->count) ; 
miVector *bbox_min = mi_eval_vector (&params->bbox_min) ; 
miVector *bbox_max = mi_eval_vector (&params->bbox_max) ; 
miScalar edge_length_max = *mi_eval_scalar (&params->edge_length_max) ; 
char* name = 
miaux_tag_to_string(*mi_eval_tag(&params->name), "::triangles") ; 
mi_srandom(*mi_eval_integer (&params->random_seed) ) ; 
obj = mi_api_object_begin(mi_mem_strdup (name) ) ; 
obj->visible = miTRUE; 
obj->shadow = 3; 
mi_api_object_group_begin(0.0); 
for (vertex_index = 0; vertex_index < count * 3; vertex_index += 3) 
miaux_add_random_triangle( 
vertex_index, edge_length_max, bbox_min, bbox_max) ; 
mi_api_object_group_end() ; 
return mi_geoshader_add_result(result, mi_api_object_end()) ; 
} 
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declare shader 

geometry "object_file" ( 
string "name", 
string "filename", 


vector "bbox_min" default -1 -1 -1, 
vector "bbox_max" default 111 ) 
version 1 


end declare 


#include <string.h> 
#include <math.h> 
#include "shader.h" 
#include "geoshader.h" 
#include "miaux.h" 


struct object_file { 


miTag name; 

miTag filename; 
miVector bbox_min; 
miVector bbox_max; 
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int object_file_version(void) { return 1; } 


miBoolean object_file ( 


miTag *result, miState *state, struct object_file *params 


if (!(mame = miaux_tag_to_string(*mi_eval_tag(&params->name), NULL)) || 
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!'(filename = miaux_tag_to_string(*mi_eval_tag(&params->filename), NULL))) 


*mi_eval_vector (&params->bbox_min) , 
*mi_eval_vector (&params->bbox_max) )) ; 


{ 
char *name, *filename; 
return miFALSE; 
return mi_geoshader_add_result ( 
result, 
miaux_object_from_file(name, filename, 
t 
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declare shader 
geometry "instanced_object_file" ( 
string "name", 
string "filename", 
material "material", 


vector "bbox_min" default -1 -1 -1, 
vector "bbox_max" default i i 1, 


array vector "positions" ) 
version 1 
end declare 


#include <string.h> 
#include <math.h> 
#include "shader.h" 
#include "geoshader.h" 
#include "miaux.h" 


struct instanced_object_file { 
miTag name; 
miTag filename; 
miTag material; 
miVector bbox_min; 
miVector bbox_max; 
int i_positions; 
int n_positions; 
miVector positions [1]; 


Fy 


int instanced_object_file_version(void) { return 1; } 


miBoolean instanced_object_file ( 


miTag *result, miState *state, struct instanced_object_file *params 


| 
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ch ee 

static int instance_index; /* Geometry shaders are single-threaded. */ 

char *filename, *name, instance_name[1024] ; 

milnstance *instance; 

miTag object_tag, instance_tag; 

int position_count = *mi_eval_integer (&params->n_positions) ; 

miVector *positions = mi_eval_vector(params->positions) + 
*mi_eval_integer (&params->i_positions) ; 


if (!(mame = miaux_tag_to_string(*mi_eval_tag(&params->name), NULL)) || 
!'(filename = miaux_tag_to_string(*mi_eval_tag(&params->filename), NULL) )) 
return miFALSE; 


object_tag = miaux_object_from_file(name, filename, 
*mi_eval_vector (&params->bbox_min) , 
*mi_eval_vector (kparams->bbox_max) ) ; 


for (i = 0; i < position_count; i++, positions++) { 
miMatrix matrix; 
miTag material_tag; 
sprintf(instance_name, "%s-/d", name, instance_indext++) ; 
if (!(instance = mi_api_instance_begin(mi_mem_strdup(instance_name) ) ) ) 
return miFALSE; 


mi_matrix_ident (matrix) ; 

matrix[12] = positions->x; 

matrix[13] = positions->y; 

matrix[14] = positions->z; 

mi_matrix_copy(instance->tf.local_to_global, matrix); 

mi_matrix_invert (instance->tf.global_to_local, 
instance->tf.local_to_global) ; 


material_tag = *mi_eval_tag(&params->material) ; 
if (material_tag) 
instance->material = mi_phen_clone(state, material_tag) ; 


instance_tag = mi_api_instance_end(0, object_tag, 0); 

if (instance_tag == miNULLTAG || 
mi_geoshader_add_result(result, instance_tag) == miFALSE) 
return miFALSE; 


} 
return miTRUE; 
t, 
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declare shader 
geometry "hair_geo_2v" ( 
string "name", 
scalar "radius" default .1, 
vector "start" default -0.5 0 0, 


vector "end" default 0.500 ) 
version 1 
apply material 
end declare 


#include "shader.h" 
#include "geoshader.h" 
#include "miaux.h" 


miBoolean hair_geo_2v_callback(miTag tag, void *ptr); 


typedef struct { 
miTag name; 
miScalar radius; 
miVector start; 
miVector end; 

} hair_geo_2v_t; 


int hair_geo_2v_version(void) { return 1; } 


void hair_geo_2v_bbox(mi0bject *obj, void* params) 


| 
hair_geo_2v_t *p = (hair_geo_2v_t*) params; 
miScalar bbox_increase = p->radius + .001; 
miaux_init_bbox(obj) ; 
miaux_adjust_bbox(obj, &p->start, bbox_increase) ; 
miaux_adjust_bbox(obj, &p->end, bbox_increase) ; 
miaux_describe_bbox (obj) ; 

} 


miBoolean hair_geo_2v ( 
miTag *result, miState *state, hair_geo_2v_t *params ) 
1. 
hair_geo_2v_t *p = (hair_geo_2v_t*)mi_mem_allocate(sizeof (hair_geo_2v_t)) ; 
p->name = *mi_eval_tag(&params->name) ; 
p->radius = *mi_eval_scalar(&params->radius) ; 
p->start = *mi_eval_vector(&params->start) ; 
p->end *mi_eval_vector (&params->end) ; 


miaux_define_hair_object ( 
p->name, hair_geo_2v_bbox, p, result, hair_geo_2v_callback) ; 


return miTRUE; 


} 


miBoolean hair_geo_2v_callback(miTag tag, void *params) 
{ 

miHair_list *hair_list; 

miScalar *hair_scalars; 

miGeoIndex *hair_indices; 

hair_geo_2v_t *p = (hair_geo_2v_t*)params; 
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int hair_scalar_count = 7; 


mi_api_incremental (miTRUE) ; 
miaux_define_hair_object(p->name, hair_geo_2v_bbox, p, NULL, NULL); 


hair_list = mi_api_hair_begin(); 
hair_list->degree = 1; 
mi_api_hair_info(0O, ’r’, 1); 


hair_scalars = mi_api_hair_scalars_begin(hair_scalar_count) ; 
*hair_scalars++ = p->radius; 

*hair_scalarst++ = p->start.x; 

*hair_scalars++ = p->start.y; 

*hair_scalarst++ = p->start.z; 

*xhair_scalarst++ = p->end.x; 

*hair_scalars++ = p->end.y; 

*hair_scalarst+t+ = p->end.z; 
mi_api_hair_scalars_end(hair_scalar_count) ; 


hair_indices = mi_api_hair_hairs_begin(2) ; 
hair_indices[0O] = 0; 

hair_indices[1] = 7; 
mi_api_hair_hairs_end() ; 


mi_api_hair_end(); 
mi_api_object_end() ; 


return miTRUE; 
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declare shader 
color "hair_color_bary" 


apply material 
version 1 
end declare 


#include "shader.h" 
int hair_color_bary_version(void) { return 1; } 


miBoolean hair_color_bary ( 

miColor *result, miState *state, void *params  ) 
{ 

result->r = state->bary [0]; 

result->g = state->bary[1]; 

result->b = 0; 

return miTRUE; 
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declare shader 

geometry "hair_geo_4v" ( 
string "name", 
scalar "radius" default .1, 
vector "vi" default -1.5 
vector "v2" default -.5 
vector "v3" default oO 
vector "v4" default 1.5 


0 0, 

0 

0 

0 0, 
integer "approximation" default 2, 
integer "degree" default 1 

version 1 


apply material 
end declare 


0 
0 
0 
0) 
a 
) 


#include "shader.h" 
#include "geoshader.h" 
#include "miaux.h" 


miBoolean hair_geo_4v_callback(miTag tag, void *ptr); 


typedef struct { 
miTag name; 
miScalar radius; 
miVector v1; 
miVector v2; 
miVector v3; 
miVector v4; 
milnteger approximation; 
miInteger degree; 
} hair_geo_4v_t; 


int hair_geo_4v_version(void) { return 1; } 


void hair_geo_4v_bbox(mi0bject *obj, void* params) 
{ 
hair_geo_4v_t *p = (hair_geo_4v_t*) params; 
miScalar bbox_increase = p->radius + .001; 
miaux_init_bbox(obj) ; 
miaux_adjust_bbox(obj, &p->vi, bbox_increase) ; 
miaux_adjust_bbox(obj, &p->v2, bbox_increase) ; 
miaux_adjust_bbox(obj, &p->v3, bbox_increase) ; 
miaux_adjust_bbox(obj, &p->v4, bbox_increase) ; 
miaux_describe_bbox (obj) ; 


} 


miBoolean hair_geo_4v ( 
miTag *result, miState *state, hair_geo_4v_t *params  ) 


{ 
hair_geo_4v_t *p = (hair_geo_4v_t*)mi_mem_allocate (sizeof (hair_geo_4v_t)); 
p->radius = *mi_eval_scalar (&params->radius) ; 
p->vi1 = *mi_eval_vector(&params->v1) ; 
p->v2 = *mi_eval_vector (&params->v2) ; 


p->v3 = *mi_eval_vector (&params->v3) ; 
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} 


p->v4 = *mi_eval_vector (&params->v4) ; 
p->approximation = *mi_eval_integer (&params->approximation) ; 
p->degree *mi_eval_integer (&params->degree) ; 


miaux_define_hair_object( 


p->name, hair_geo_4v_bbox, p, result, hair_geo_4v_callback) ; 


return miTRUE; 


miBoolean hair_geo_4v_callback(miTag tag, void *params) 


{ 


miHair_list *hair_list; 

miScalar *hair_scalars; 

miGeoIndex *hair_indices; 

hair_geo_4v_t *p = (hair_geo_4v_t *)params; 

int hair_count = 1, hair_scalar_count = 4 * 3 + 1; 


mi_api_incremental (miTRUE) ; 


miaux_define_hair_object(p->name, hair_geo_4v_bbox, p, NULL, NULL); 


hair_list = mi_api_hair_begin() ; 
hair_list->approx = p->approximation; 
hair_list->degree = p->degree; 
mi_api_hair_info(0O, ’r’, 1); 


hair_scalars = mi_api_hair_scalars_begin(hair_scalar_count) ; 
*hair_scalars++ = p->radius; 
miaux_append_hair_vertex(&hair_scalars, &p->v1); 
miaux_append_hair_vertex(&hair_scalars, &p->v2); 
miaux_append_hair_vertex(&hair_scalars, &p->v3) ; 
miaux_append_hair_vertex(&hair_scalars, &p->v4); 
mi_api_hair_scalars_end(hair_scalar_count) ; 


hair_indices = mi_api_hair_hairs_begin(hair_count + 1); 
hair_indices[0] = 0; 

hair_indices[1i] = hair_scalar_count; 
mi_api_hair_hairs_end() ; 


mi_api_hair_end() ; 
mi_api_object_end() ; 


return miTRUE; 
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hair geo 4v_texture Page 307 


declare shader 
geometry "hair_geo_4v_texture" 

string "name", 
vector "vi" default -1. 
vector "v2" default 
vector "v3" default 
vector "v4" default 
scalar "root_radius" default .1, 


color "root_color" default 00 0 1, 
scalar "tip_radius" default .01, 
color "tip_color" default 111 0, 
integer "approximation" default 2, 
integer "degree" default 1 ) 

version 1 


apply material 
end declare 


#include "shader.h" 
#include "geoshader.h" 
#include "miaux.h" 


miBoolean hair_geo_4v_texture_callback(miTag tag, void *ptr) ; 


typedef struct { 
miTag name; 
miVector pl; 
miVector p2; 
miVector p3; 
miVector p4; 
miScalar root_radius; 
miColor root_color; 
miScalar tip_radius; 
miColor tip_color; 
miInteger approximation; 
milnteger degree; 

} hair_geo_4v_texture_t; 


int hair_geo_4v_texture_version(void) { return 1; } 


void hair_geo_4v_texture_bbox(mi0bject *obj, void* params) 


{ 
hair_geo_4v_texture_t *p = (hair_geo_4v_texture_t*) params; 
double max_radius = miaux_max(p->root_radius, p->tip_radius) + .001; 
miaux_init_bbox(obj) ; 
miaux_adjust_bbox(obj, &p->p1, max_radius) ; 
miaux_adjust_bbox(obj, &p->p2, max_radius) ; 
miaux_adjust_bbox(obj, &p->p3, max_radius) ; 
miaux_adjust_bbox(obj, &p->p4, max_radius) ; 
miaux_describe_bbox (obj) ; 
} 


miBoolean hair_geo_4v_texture ( 
miTag *result, miState *state, hair_geo_4v_texture_t *params ) 
1 


hair_geo_4v_texture_t *p = 
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(hair_geo_4v_texture_t*) mi_mem_allocate(sizeof (hair_geo_4v_texture_t)) ; 


p->pi = *mi_eval_vector (&params->p1) ; 

p->p2 = *mi_eval_vector(&params->p2) ; 

p->p3 = *mi_eval_vector (&params->p3) ; 

p->p4 = *mi_eval_vector (&params->p4) ; 

p->root_radius = *mi_eval_scalar(&params->root_radius) ; 
p->root_color = *mi_eval_color(&params->root_color) ; 
p->tip_radius = *mi_eval_scalar(&params->tip_radius) ; 
p->tip_color = *mi_eval_color(&params->tip_color) ; 
p->approximation = *mi_eval_integer (&params->approximation) ; 
p->degree = *mi_eval_integer (&params->degree) ; 


miaux_define_hair_object ( 
p->name, hair_geo_4v_texture_bbox, p, result, 
hair_geo_4v_texture_callback) ; 


return miTRUE; 


} 


miBoolean hair_geo_4v_texture_callback(miTag tag, void *ptr) 
{ 
miHair_list *hair_list; 
miScalar *hair_scalars; 
miGeoIndex *hair_indices; 
hair_geo_4v_texture_t *p = (hair_geo_4v_texture_t *)ptr; 
nt i; 


int hair_count = 1; 

int vertices_per_hair = 4; 

int scalars_per_vertex = 8; 

int hair_scalar_count = vertices_per_hair * scalars_per_vertex; 


miVector vertices [4]; 
vertices[0] = p->p1; 
vertices[1] = p->p2; 
vertices[2] = p->p3; 
vertices[3] = p->p4; 


mi_api_incremental (miTRUE) ; 


miaux_define_hair_object ( 
p->name, hair_geo_4v_texture_bbox, p, NULL, NULL); 


hair_list = mi_api_hair_begin() ; 
hair_list->approx = p->approximation; 
hair_list->degree = p->degree; 

Mi api Veit Veeotr, "Fr" 1): 
mi_api_hair_info(1i, ’t’, 4); 


hair_scalars = mi_api_hair_scalars_begin(hair_scalar_count) ; 
for (i = 0; i < vertices_per_hair; i++) 
miaux_append_hair_data( 
&hair_scalars, &vertices[i], 
miaux_fit(i, 0, vertices_per_hair, 0, 1), 
p->root_radius, &p->root_color, p->tip_radius, &p->tip_color) ; 
mi_api_hair_scalars_end(hair_scalar_count) ; 
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hair_indices = mi_api_hair_hairs_begin(hair_count + 1); 
hair_indices[0] = 0; 

hair_indices[1] = hair_scalar_count; 
mi_api_hair_hairs_end() ; 


mi_api_hair_end() ; 
mi_api_object_end() ; 


return miTRUE; 
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declare shader 
color "hair_color_texture" () 


apply material 
version 1 
end declare 


#include "shader.h" 
#include "miaux.h" 


int hair_color_texture_version(void) { return 1; } 


miBoolean hair_color_texture ( 
miColor *result, miState *state, void *params ) 

{ 
miColor hair_color, opacity, background; 
miaux_copy_color(&hair_color, (miColor*)&state->tex_list[0]); 


if (state->type == miRAY_SHADOW) { 
miScalar transparency = 1.0 - hair_color.a; 
result->r *= miaux_shadow_breakpoint (hair_color.r, transparency, 0.5); 
result->g *= miaux_shadow_breakpoint (hair_color.g, transparency, 0.5); 
result->b *= miaux_shadow_breakpoint (hair_color.b, transparency, 0.5); 
return miaux_all_channels_equal(result, 0.0) ? miFALSE : miTRUE; 

} 

miaux_copy_color(result, &hair_color) ; 

miaux_set_channels(&opacity, result->a) ; 

mi_opacity_set(state, opacity) ; 

if (result->a < 1.0) { 
mi_trace_transparent (&background, state); 
miaux_blend_channels(result, &background, &opacity) ; 

J 


return miTRUE; 
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declare shader 
geometry "hair_geo_row" ( 
string "name", 
integer "count" default 1, 
scalar "radius" default .01, 
vector “bbox_min” default -.5 -.5 -.5, 
vector "bbox_max" default .5 .5 .5, 


scalar "y_offset_max" default .01, 

scalar "z_offset_max" default .01, 

integer "approximation" default 100, 

integer "degree" default 3, 

integer "random_seed" default 1955 ) 
version 1 


apply material 
end declare 


#include "shader.h" 
#include "geoshader.h" 
#include "miaux.h" 


typedef struct { 
miTag name; 
milnteger count; 
miScalar radius; 
miVector bbox_min; 
miVector bbox_max; 
miScalar y_offset_max; 
miScalar z_offset_max; 
milnteger approximation; 
miInteger degree; 
milnteger random_seed; 
} hair_geo_row_t; 


int hair_geo_row_version(void) { return 1; } 


void hair_geo_row_bbox(miObject *obj, void* params) 


{ 
hair_geo_row_t *p = (hair_geo_row_t*) params; 
obj->bbox_min = p->bbox_min; 
obj->bbox_max = p->bbox_max; 

f 


miBoolean hair_geo_row_callback(miTag tag, void *ptr); 


miBoolean hair_geo_row ( 
miTag *result, miState *state, hair_geo_row_t *params  ) 
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3 
hair_geo_row_t *p = 
(hair_geo_row_t*) mi_mem_allocate(sizeof (hair_geo_row_t)); 
p->name = *mi_eval_tag(&params->name) ; 
p->count = *mi_eval_integer (&params->count) ; 
p->radius = *mi_eval_scalar(&params->radius) ; 
p->bbox_min = *mi_eval_vector (kparams->bbox_min) ; 
p->bbox_max = *mi_eval_vector (&params->bbox_max) ; 
p->y_offset_max = *mi_eval_scalar(&params->y_offset_max) ; 
p->z_offset_max = *mi_eval_scalar(&params->z_offset_max) ; 
p->approximation = *mi_eval_integer (&params->approximation) ; 
p->degree = *mi_eval_integer (kparams-—>degree) ; 
p->random_seed = *mi_eval_integer(&params->random_seed) ; 
miaux_define_hair_object ( 
p->name, hair_geo_row_bbox, p, result, hair_geo_row_callback) ; 
return miTRUE; 
} 


miBoolean hair_geo_row_callback(miTag tag, void *ptr) 
{ 
miHair_list *hair_list; 
miGeoIndex *harray; 
miScalar *hair_scalars; 
int i, h, per_hair_data_count, vertex_count, vertex_size, 
per_hair_scalar_count, total_scalar_count; 
hair_geo_row_t *p = (hair_geo_row_t *)ptr; 
miScalar x, y_offset, z_offset, 
yoff_max = p->y_offset_max, zoff_max = p->z_offset_max; 


mi_api_incremental (miTRUE) ; 
miaux_define_hair_object(p->name, hair_geo_row_bbox, p, NULL, NULL); 


hair_list = mi_api_hair_begin() ; 
hair_list->approx = p->approximation; 
hair_list->degree = p->degree; 
mi_api_hair_info(0O, ’r’, 1); 
mi_api_hair_info(0O, ’t’, 1); 


per_hair_data_count = 2; /* Radius and random value */ 
vertex_count = 4; 
vertex_size = 3; 
per_hair_scalar_count = 

vertex_count * vertex_size + per_hair_data_count ; 
total_scalar_count = p->count * per_hair_scalar_count; 


hair_scalars = mi_api_hair_scalars_begin(total_scalar_count) ; 
mi_srandom(p->random_seed) ; 


for (i = 0; i < p->count; itt) { 
x = miaux_random_range(p->bbox_min.x, p->bbox_max.x) ; 


y_offset = miaux_random_range(-yoff_max, yoff_max) ; 
z_offset miaux_random_range(-zoff_max, zoff_max) ; 


*hair_scalars++ = p->radius; 
*hair_scalars++ miaux_random_range(0.0, 1.0); 
*hair_scalarst++ ae 
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*hair_scalars++ = p->bbox_min.y + yoff_max + y_offset; 
*hair_scalars++ = p->bbox_min.z + zoff_max + z_offset; 
*hair_scalarst++ = x; 

*hair_scalars++ = p->bbox_max.y - yoff_max + y_offset; 
*hair_scalarst++ = p->bbox_min.z zoff_max + z_offset; 
*hair_scalars++ = x; 
*hair_scalarst++ = p->bbox_max.y yoff_max + y_offset; 
*hair_scalarst++ = p->bbox_max.z - zoff_max + z_offset; 
*hair_scalarst++ = x; 
*hair_scalars++ = p->bbox_min.y + yoff_max + y_offset; 
*hair_scalars++ = p->bbox_max.z - zoff_max + z_offset; 
} 
mi_api_hair_scalars_end(total_scalar_count) ; 
harray = mi_api_hair_hairs_begin(p->count + 1); 
for (h=0; h < p->count + 1; h++) 
harray[h] = h * per_hair_scalar_count; 
mi_api_hair_hairs_end() ; 
mi_api_hair_end() ; 
mi_api_object_end() ; 
return miTRUE; 
} 
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declare shader 
color "hair_color_light" ( 
color "ambient" default 
color "diffuse" default 
color "specular" default 


scalar "exponent" default 
scalar "root_opacity" default 1, 


scalar "tip_opacity" default 0, 
scalar "color_variance" default .1, 
array light "lights" ) 
version 1 
apply material 
end declare 


#include "shader.h" 
#include "miaux.h" 


struct hair_color_light { 


miColor ambient; 
miColor diffuse; 
miColor specular; 


miScalar exponent ; 
miScalar root_opacity; 
miScalar tip_opacity; 
miScalar color_variance; 


550 B Shader source code 


int i_light ; 

int n_light ; 

miTag light [1] ; 
}; 


int hair_color_light_version(void) { return 1; } 


void hair_color_variance( 
miColor *result, miState *state, struct hair_color_light* params) 


1 
miScalar maximum_variance = *mi_eval_scalar(&params->color_variance) ; 
miScalar color_variance = 
miaux_fit(state->tex_list[0].x, 0.0, 1.0, 
1.0 - maximum_variance, 1.0 + maximum_variance) ; 
*xresult = *mi_eval_color(&params->diffuse) ; 
miaux_scale_color(result, color_variance) ; 
miaux_clamp_color(result) ; 
r 


miScalar hair_alpha(miState *state, struct hair_color_light* params) 
{ 
return miaux_fit(state->bary[1], 0.0, 1.0, 
*mi_eval_scalar (&params->root_opacity) , 
*mi_eval_scalar(&params->tip_opacity)) ; 


miBoolean hair_shadow(miColor *result, miColor *diffuse, miScalar alpha) 
{ 
miScalar threshold = 0.001; 
miScalar transparency = 1.0 - alpha; 
result->r *= miaux_shadow_breakpoint(diffuse->r, transparency, 0.2); 
result->g *= miaux_shadow_breakpoint (diffuse->g, transparency, 0.2); 
result->b *= miaux_shadow_breakpoint (diffuse->b, transparency, 0.2); 
if (result->r < threshold && 
result->g < threshold && 
result->b < threshold) 
return miFALSE; 
else 
return miTRUE; 
} 


miBoolean hair_color_light ( 

miColor *result, miState *state, struct hair_color_light *params  ) 
{ 

int i, light_count, light_sample_count ; 

miColor diffuse, sum, light_color, *specular; 

miVector direction_toward_light, to_camera; 

miScalar dot_nl, alpha; 

miTag *light; 

miVector hair_tangent = state->derivs[0] ; 

miVector original_normal = state->normal; 


hair_color_variance(&diffuse, state, params); 
alpha = hair_alpha(state, params) ; 


if (state->type == miRAY_SHADOW) 
return hair_shadow(result, &diffuse, alpha); 
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state->normal.x = state->normal.y = state->normal.z = 0.0f; 
to_camera = state->dir; 

mi_vector_neg(&to_camera) ; 
mi_vector_normalize(xhair_tangent) ; 


specular = mi_eval_color(&params->specular) ; 
*xresult = *mi_eval_color(&params->ambient) ; 
result->a = alpha; 


miaux_light_array(&light, &light_count, state, 
&params->i_light, &params->n_light, params->light) ; 


for (i = O; i < light count; i++, light++).+ 
miaux_set_channels(&sum, 0); 
light_sample_count = 0; 
while (mi_sample_light(&light_color, &direction_toward_light, &dot_nl, 
state, *light, &light_sample_count)) { 
miaux_add_diffuse_hair_component ( 
&sum, &hair_tangent, &direction_toward_light, 
&diffuse, &light_color) ; 
miaux_add_specular_hair_component ( 
&sum, &hair_tangent, &direction_toward_light, &to_camera, 
specular, &light_color) ; 
} 
if (light_sample_count) 
miaux_add_scaled_color(result, &sum, 1.0/light_sample_count) ; 
? 
state->normal = original_normal; 
if (result->a < 0.999) 
miaux_add_transparent_hair_component (result, state); 
return miTRUE; 
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declare shader 
geometry "hair_geo_curl" ( 

string "name", 
integer "count" default 1, 
scalar "root_radius" default .01, 
scalar "tip_radius" default .0001, 
vector "center" default O 0 0O, 
scalar "length_min" default .5, 
scalar "length_max" default 1, 


scalar "spiral_turns_min" default 2, 

scalar "spiral_turns_max" default 3, 

scalar "spiral_radius_min" default .01, 

scalar "spiral_radius_max" default .03, 

scalar "segment_length" default .05, 

integer "random_seed" default 1955 ) 
version 1 


apply material 
end declare 


#include "shader.h" 
#include "geoshader.h" 
#include "miaux.h" 


typedef struct { 
miTag name; 
milnteger count; 
miScalar root_radius; 
miScalar tip_radius; 
miVector center; 
miScalar length_min; 
miScalar length_max; 
miScalar spiral_turns_min; 
miScalar spiral_turns_max; 
miScalar spiral_radius_min; 
miScalar spiral_radius_max; 
miScalar segment_length; 
miInteger random_seed; 

} hair_geo_curl_t; 


int hair_geo_curl_version(void) { return 1; } 


void hair_geo_curl_bbox(mi0bject *obj, void* params) 


{ 
hair_geo_curl_t *p = (hair_geo_curl_t*)params; 
obj->bbox_min.x = p->center.x - p->length_max; 
obj->bbox_min.y = p->center.y - p->length_max; 
obj->bbox_min.z = p->center.z - p->length_max; 
obj->bbox_max.x = p->center.x + p->length_max; 
obj->bbox_max.y = p->center.y + p->length_max; 
obj->bbox_max.z = p->center.z + p->length_max; 

} 


miBoolean hair_geo_curl_callback(miTag tag, void *ptr); 


miBoolean hair_geo_curl ( 
miTag *result, miState *state, hair_geo_curl_t *params ) 


hair_geo_curl 


i! 

hair_geo_curl_t *p = 
(hair_geo_curl_t*)mi_mem_allocate (sizeof (hair_geo_curl_t)); 
p->name = *mi_eval_tag(&params->name) ; 
p->count = *mi_eval_integer (&params-—>count) ; 
p->root_radius = *mi_eval_scalar (&params->root_radius) ; 
p->tip_radius = *mi_eval_scalar(&params->tip_radius) ; 
p->center = *mi_eval_vector (&params->center) ; 
p->length_min = *mi_eval_scalar(&params->length_min) ; 
p->length_max = *mi_eval_scalar (&params->length_max) ; 
p->spiral_turns_min = *mi_eval_scalar(&params->spiral_turns_min) ; 
p->spiral_turns_max = *mi_eval_scalar(&params->spiral_turns_max) ; 
p->spiral_radius_min = *mi_eval_scalar(params->spiral_radius_min) ; 
p->spiral_radius_max = *mi_eval_scalar(&params->spiral_radius_max) ; 
p->segment_length = *mi_eval_scalar (&params->segment_length) ; 
p->random_seed = *mi_eval_integer (&params->random_seed) ; 
miaux_define_hair_object ( 
p->name, hair_geo_curl_bbox, p, result, hair_geo_curl_callback) ; 

return miTRUE; 

} 


typedef struct { 
miVector hair_end; 
int vertex_count; 
miScalar turns; 
miScalar spiral_radius; 
} hair_spec_t; 


int create_hair_specifications ( 
hair_spec_t **hair_specs, hair_geo_curl_t *p) 


{ 
float pi_2 = M_PI * 2.0; 
int scalars_per_vertex = 4, total_scalar_count = 0, i; 
*hair_specs = 
(hair_spec_t*)mi_mem_allocate(p->count * sizeof (hair_spec_t)); 
for (i = 0; i < p->count; itt) { 
miScalar distance, length; 
hair_spec_t *spec = &((*hair_specs) [i]); 
spec->turns = 

miaux_random_range(p->spiral_turns_min, p->spiral_turns_max) ; 
spec->spiral_radius = 

miaux_random_range(p->spiral_radius_min, p->spiral_radius_max) ; 
distance = miaux_random_range(p->length_min, p->length_max) ; 
length = distance + pi_2 * spec->spiral_radius * spec->turns; 
miaux_random_point_on_sphere ( 

&(spec->hair_end), &p->center, distance) ; 
spec->vertex_count = (int) (ceil(length / p->segment_length) ) ; 
total_scalar_count += spec->vertex_count * scalars_per_vertex; 

t 
return total_scalar_count; 
F 


miBoolean hair_geo_curl_callback(miTag tag, void *ptr) 


{ 


miHair_list *hair; 
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miGeoIndex *harray; 

hair_geo_curl_t *p = (hair_geo_curl_t*) ptr; 
hair_spec_t *hair_specs; 

int i, total_scalar_count, hair_array_position; 
miScalar *hair_scalars; 


mi_srandom(p->random_seed) ; 

mi_api_incremental (miTRUE) ; 

miaux_define_hair_object(p->name, hair_geo_curl_bbox, p, NULL, NULL); 
hair = mi_api_hair_begin() ; 

hair->approx = hair->degree = 1; 

ni_api_hair_infoti; "x", dh; 


total_scalar_count = create_hair_specifications(xhair_specs, pis 
hair_scalars = mi_api_hair_scalars_begin(total_scalar_count) ; 


for (i = 0; i < p->count; i++) { 
float angle_offset = miaux_random_range(0, M_PI * 2); 
miaux_hair_spiral ( 
&hair_scalars, &p->center, &hair_specs[i].hair_end, 
hair_specs[i].turns, hair_specs[i].vertex_count, angle_offset, 
hair_specs[i].spiral_radius, p->root_radius, p->tip_radius) ; 
} 


mi_api_hair_scalars_end(total_scalar_count) ; 


harray = mi_api_hair_hairs_begin(p->count + 1); 
hair_array_position = 0; 
for (i = 0; i < p->count + 1; i++) { 
harrayli] = hair_array_position; 
if (i < p->count) 
hair_array_position += hair_specs[i].vertex_count * 4; 
} 


mi_api_hair_hairs_end() ; 
mi_api_hair_end() ; 
mi_api_object_end() ; 


mi_mem_release(hair_specs) ; 


return miTRUE; 


i 
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declare shader 
geometry "hair_geo_datafile" ( 
string "name", 
scalar "radius" default .1, 


string "particle_filename" ) 
version 1 
apply material 
end declare 


#include "shader.h" 
#include "geoshader.h" 
#include "miaux.h" 


miBoolean hair_geo_datafile_callback(miTag tag, void *ptr); 
typedef struct { 

miTag name; 

miScalar radius; 

miTag particle_filename; 
} hair_geo_datafile_t; 


int hair_geo_datafile_version(void) { return 1; } 


void hair_geo_datafile_bbox(mi0bject *obj, void* params) 


) 
hair_geo_datafile_t *hairdata = (hair_geo_datafile_t*) params; 
char* particle_filename; 
particle_filename = 
miaux_tag_to_string(hairdata->particle_filename, NULL) ; 
if (particle_filename == NULL) 
mi_fatal("Particle filename required for hair_geo_datafile."); 
miaux_hair_data_file_bounding_box( 
particle_filename, 
&obj->bbox_min.x, &obj->bbox_min.y, &obj->bbox_min.z, 
&obj->bbox_max.x, &obj->bbox_max.y, &obj->bbox_max.z) ; 
t 


miBoolean hair_geo_datafile ( 
miTag *result, miState *state, hair_geo_datafile_t *params ) 


1, 
hair_geo_datafile_t *hairdata = 
(hair_geo_datafile_t*)mi_mem_allocate(sizeof (hair_geo_datafile_t)) ; 
hairdata->radius = *mi_eval_scalar(&params->radius) ; 
hairdata->particle_filename = *mi_eval_tag(&params->particle_filename) ; 
miaux_define_hair_object ( 
hairdata->name, hair_geo_datafile_bbox, hairdata, result, 
hair_geo_datafile_callback) ; 
return miTRUE; 
: 


miBoolean hair_geo_datafile_callback(miTag tag, void *ptr) 
y! 
miHair_list *hair; 
hair_geo_datafile_t *hairdata = (hair_geo_datafile_t *)ptr; 
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mi_api_incremental (miTRUE) ; 
miaux_define_hair_object( 
hairdata->name, hair_geo_datafile_bbox, hairdata, NULL, NULL); 
hair = mi_api_hair_begin() ; 
hair->approx = hair->degree = 1; 


miaux_read_hair_data_file( 
miaux_tag_to_string(hairdata->particle_filename, NULL) , 
hairdata->radius) ; 

mi_api_hair_end() ; 

mi_api_object_end() ; 

return miTRUE; 


} 
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declare shader 
color "hair_color_fire" ( 
color "transparency" default 0.5 0.5 0.5 ) 


version 1 
apply material 
end declare 


#include "shader.h" 
#include "miaux.h" 


struct hair_color_fire { 
miColor transparency; 


a 
int hair_color_fire_version(void) { return 1; } 


miBoolean hair_color_fire ( 
miColor *result, miState *state, struct hair_color_fire *params ) 
1 
miScalar keys[6] = {0.0, .2, .4, .6, .9, 1.0}; 
miColor colors[6] = {{1.2, 1.2, .7}, 
115 by -<B}5 
{i1, .5, O}, 
1i, «2s OF, 
th, «v8 efi, 
{0, 0, OF}; 
miColor *transparency = mi_eval_color(&params->transparency) ; 
miScalar age = state->tex_list[0].x; 
int i; 
for (i = 4; i >=0; i--) f{ 
if (age >= keys[i]) { 
miaux_color_fit(result, age, 
keysli], keys[it+1], &colors[i], &colors[it+1]); 
break; 
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} 
t 


miaux_blend_transparency(result, state, transparency) ; 


return miTRUE; 


} 
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declare shader 
color "chrome_ramp" () 
version 1 


apply environment, texture 
end declare 


#include "shader.h" 
#include "miaux.h" 


#define RAMPSIZE 1024 


typedef struct { 
int r_size, g_size, b_size; 
miScalar r[RAMPSIZE] ; 
miScalar g[RAMPSIZE] ; 
miScalar b[RAMPSIZE] ; 

} channel_ramp_table; 


static channel_ramp_table *ramp; 


miBoolean chrome_ramp_init ( 
miState *state, void *params, miBoolean *instance_init_required) 


{ 
int key_count = 4; 
miScalar key_positions[] = {0, 0.49, 0.51, 1.0}; 
miScalar red[] = {0.95, 0.68, 0.95, 0.5}; 
miScalar green[] = {0.85, 0.6, 0.95, 0.4}; 
miScalar blue[] = {0.75, 0.48, 1.0, 0.9}; 
ramp = (channel_ramp_table*)mi_mem_allocate(sizeof (channel_ramp_table)) ; 
miaux_piecewise_sinusoid(ramp->r, RAMPSIZE, key_count, key_positions, red); 
miaux_piecewise_sinusoid(ramp->g, RAMPSIZE, key_count, key_positions, green) ; 
miaux_piecewise_sinusoid(ramp->b, RAMPSIZE, key_count, key_positions, blue); 
return miTRUE; 

t 


miBoolean chrome_ramp_exit(miState *state, void *params) 
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mi_mem_release(ramp) ; 
return miTRUE; 
i 


int chrome_ramp_version(void) { return 1; } 


miBoolean chrome_ramp ( 
miColor *result, miState *state, void *params ) 


{ 
miScalar altitude = miaux_altitude(state) ; 
result->r = miaux_interpolated_lookup(ramp->r, RAMPSIZE, altitude) ; 
result->g = miaux_interpolated_lookup(ramp->g, RAMPSIZE, altitude) ; 
result->b = miaux_interpolated_lookup(ramp->b, RAMPSIZE, altitude) ; 
return miTRUE; 
} 
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declare shader 
color "channel_ramp" ( 
array scalar "Keys", 
array scalar "r", 


array scalar "g", 
array scalar "b" ) 
version 1 
apply environment, texture 
end declare 


#include "shader.h" 
#include "miaux.h" 


#define RAMPSIZE 1024 


typedef struct { 
int r_size, g_size, b_size; 
miScalar r[RAMPSIZE] ; 
miScalar g[RAMPSIZE] ; 
miScalar b[RAMPSIZE] ; 

} channel_ramp_table; 


struct channel_ramp { 


int i_keys; 
int n_keys; 
miScalar keys[1]; 
int FO oa 
int nT; 


miScalar r[1]; 
int i_g; 


channel_ramp 


Ki; 


int n_g; 
miScalar g[1]; 
int i_G; 
Int n_b; 


miScalar b[1]; 


int channel_ramp_version(void) { return 1; } 


miBoolean channel_ramp_init ( 


{ 


t 


miState *state, struct channel_ramp *params, miBoolean *instance_init_required) 


if (params == NULL) { /* Main shader init (not an instance) */ 
*instance_init_required = miTRUE; 
} else { /* Instance initialization */ 


int n keys, nr, Bug, nb; 
miScalar *keys, *red, *green, *blue; 
channel_ramp_table *ramp; 


n_keys = *mi_eval_integer (&params->n_keys) ; 
keys = mi_eval_scalar(params->keys) + 
*mi_eval_integer (&params->i_keys) ; 


if ((m_r = *mi_eval_integer(&params->n_r)) != n_keys) 
mi_fatal("Incorrect number of red values: %d", n_r); 
red = mi_eval_scalar(params->r) + *mi_eval_integer (&params->i_r) ; 


if ((n_g = *mi_eval_integer(&params->n_g)) != n_keys) 
mi_fatal("Incorrect number of green values: 74d", n_g); 
green = mi_eval_scalar(params->g) + *mi_eval_integer(&params->i_g) ; 


if ((n_b = *mi_eval_integer(&params->n_b)) != n_keys) 
mi_fatal("Incorrect number of blue values: %d", n_b); 
blue = mi_eval_scalar(params->b) + *mi_eval_integer (&params->i_b) ; 


ramp = miaux_user_memory_pointer(state, sizeof(channel_ramp_table)); 


miaux_piecewise_sinusoid(ramp->r, RAMPSIZE, n_keys, keys, red); 
miaux_piecewise_sinusoid(ramp->g, RAMPSIZE, n_keys, keys, green); 
miaux_piecewise_sinusoid(ramp->b, RAMPSIZE, n_keys, keys, blue); 
} 
return miTRUE; 


miBoolean channel_ramp_exit(miState *state, void *params) 


| 
t 


return miaux_release_user_memory("channel_ramp", state, params) ; 


miBoolean channel_ramp ( 


{ 


miColor *result, miState *state, struct channel_ramp *params  ) 


miScalar altitude = miaux_altitude(state) ; 
channel_ramp_table *ramp = miaux_user_memory_pointer(state, 0); 


result->r = miaux_interpolated_lookup(ramp->r, RAMPSIZE, altitude) ; 
result->g = miaux_interpolated_lookup(ramp->g, RAMPSIZE, altitude) ; 
result->b = miaux_interpolated_lookup(ramp->b, RAMPSIZE, altitude) ; 
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return miTRUE; 
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declare shader 
color "color_ramp" ( 
array color "colors" ) 


version 1 
apply environment, texture 
end declare 


#include "shader.h" 
#include "miaux.h" 


#define RAMPSIZE 1024 


struct color_ramp { 
int i_colors; 
int n colors: 
miColor colors[i1]; 


}; 
int color_ramp_version(void) { return 1; } 
miBoolean color_ramp_init ( 


miState *state, struct color_ramp *params, 
miBoolean *instance_init_required) 


{ 
if (params == NULL) { /* Main shader init (not an instance) */ 
*instance_init_required = miTRUE; 
+ else { /* Instance initialization */ 
int n_colors = *mi_eval_integer(&params->n_colors) ; 
miColor *colors = 
mi_eval_color(params->colors) + *mi_eval_integer(&params->i_colors) ; 
miColor *ramp = 
miaux_user_memory_pointer(state, sizeof(miColor) * RAMPSIZE) ; 
miaux_piecewise_color_sinusoid(ramp, RAMPSIZE, n_colors, colors) ; 
} 
return miTRUE; 
} 


miBoolean color_ramp_exit(miState *state, void *params) 
4 
return miaux_release_user_memory("color_ramp", state, params) ; 


t 
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miBoolean color_ramp ( 
miColor *result, miState *state, struct color_ramp *params ) 


t 
miColor *ramp = miaux_user_memory_pointer(state, 0); 
miaux_interpolated_color_lookup( 
result, ramp, RAMPSIZE, miaux_altitude(state) ) ; 
return miTRUE; 
i, 
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declare shader 
color "fog" ( 
scalar "full_fade_distance" default 10, 
color "fog_color" default 1 1 1 ) 


version 1 
apply volume 
end declare 


#include "shader.h" 
#include "miaux.h" 


struct fog { 
miScalar full_fade_distance; 
miColor fog_color; 


}; 
int fog_version(void) { return 1; } 


miBoolean fog ( 
miColor *result, miState *state, struct fog *params ) 


4, 
miScalar full_fade_distance = *mi_eval_scalar (&params->full_fade_distance) ; 
miColor *fog_color = mi_eval_color(&params->fog_color) ; 
if (state->dist > full_fade_distance || state->dist == 0.0) 
*result = *fog_color; 
else 
miaux_blend_colors( 
result, fog_color, result, state->dist/full_fade_distance) ; 
return miTRUE; 
} 
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declare shader 
color "ground_fog" ( 
color "fog_color" default 
color "fog density" default 
scalar "fade_start" default 


scalar '"fade_end" default 
scalar "“unit_density" default 
scalar "“march_increment" default 
version 1 
apply volume 
end declare 


#include "shader.h" 
#include "miaux.h" 


struct ground_fog { 
miColor fog_color; 
miColor fog_density; 
miScalar fade_start; 
miScalar fade_end; 
miScalar unit_density; 
miScalar march_increment ; 


rs 
int ground_fog_version(void) { return 1; } 


miBoolean ground_fog ( 
miColor *result, miState *state, struct ground_fog *params ) 
{ 
miScalar fade_start, fade_end, fog_density, distance, density_factor, 
march_increment, unit_density, accumulated_density; 
miVector march_point ; 


if (state->dist == 0) 
return miTRUE; 


fade_start = *mi_eval_scalar(&params->fade_start) ; 

fade_end = *mi_eval_scalar (&params->fade_end) ; 

fog_density = *mi_eval_scalar(&params->fog_density) ; 
march_increment = *mi_eval_scalar(&params->march_increment) ; 
unit_density = *mi_eval_scalar(&params->unit_density) ; 
accumulated_density = 0.0; 


for (distance = 0; distance < state->dist; distance += march_increment) { 
miaux_world_space_march_point(&march_point, state, distance) ; 
density_factor = miaux_fit_clamp( 
march_point.y, fade_start, fade_end, fog_density, 0.0): 
accumulated_density += density_factor * march_increment * unit_density; 
if (accumulated_density > 1.0) { 
*xresult = *mi_eval_color(&params->fog_color) ; 
return miTRUE; 
t 
t 
if (accumulated_density > 0.0) 
miaux_blend_colors(result, result, mi_eval_color(&params->fog_color), 
1.0 - accumulated_density) ; 
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return miTRUE; 


t 
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declare shader 
color "ground_fog_layers" ( 
color "fog_color" default 
color "fog density" default 
scalar "fade_start" default 
scalar '"fade_end" default 
scalar "unit_density" default 


scalar "march_increment" default 
boolean "show_layers" default 
color "full_fog_marker" default 
color "partial_fog_marker" default 
version 1 
apply volume 
end declare 


#include "shader.h" 
#include "miaux.h" 


struct ground_fog_layers { 
miColor fog_color; 
miColor fog_density; 
miScalar fade_start; 
miScalar fade_end; 
miScalar unit_density; 
miScalar march_increment ; 
miBoolean show_layers; 
miColor full_fog_marker; 
miColor partial_fog_marker ; 


}; 
int ground_fog_layers_version(void) { return 1; } 


miBoolean ground_fog_layers ( 

miColor *result, miState *state, struct ground_fog_layers *params ) 
{ 

miScalar fade_start = *mi_eval_scalar(&params->fade_start) ; 

miScalar fade_end = *mi_eval_scalar (&params->fade_end) ; 

miVector world_point, march_point; 


if (state->dist == 0.0) 
return miTRUE; 

else if (*mi_eval_boolean(&params->show_layers)) { 
miColor* full_fog_marker = 
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mi_eval_color (&params->full_fog_marker) ; 
miColor* partial_fog_marker = 
mi_eval_color (&params->partial_fog_marker) ; 


mi_point_to_world(state, &world_point, &state->point) ; 
if (world_point.y < fade_start) 
miaux_multiply_colors(result, result, full_fog_marker) ; 
else if (world_point.y < fade_end) 
miaux_multiply_colors(result, result, partial_fog_marker) ; 
} else { 
miScalar fog_density = *mi_eval_scalar(&params->fog_density) ; 
miScalar march_increment = *mi_eval_scalar(&params->march_increment) ; 
miScalar unit_density = *mi_eval_scalar(&params->unit_density) ; 
miScalar accumulated_density = 0.0, distance, density_factor; 


for (distance = 0; distance < state->dist; distance += march_increment) { 
miaux_world_space_march_point (&march_point, state, distance) ; 
density_factor = miaux_fit_clamp( 
march_point.y, fade_start, fade_end, fog density, 0.0): 
accumulated_density += 
density_factor * march_increment * unit_density; 
if (accumulated_density > 1.0) { 
*xresult = *mi_eval_color(&params->fog_color) ; 
return miTRUE; 
} 
I 
if (accumulated_density > 0.0) { 
miaux_blend_colors(result, result, mi_eval_color(&params->fog_color), 
1.0 - accumulated_density) ; 


s 
} 
return miTRUE; 
t 
Function Page 
miaux_multiply_colors 593 
miaux_world_space_march_point 603 
miaux_march_point 603 
miaux_point_along_vector 603 
miaux_fit_clamp 593 
miaux_fit 589 
miaux_blend_colors 589 
miaux_blend 589 
threshold volume Page 374 


declare shader 
color "threshold_volume" ( 
color "color" default 1111, 
vector "center" default O 0 0, 
scalar "radius" default 1, 
scalar "density_threshold" default 0, 


scalar "unit_density" default 1, 
scalar "march_increment" default 0.1 ) 
version 1 
apply volume 
end declare 


threshold_volume 


#include "shader.h" 
#include "miaux.h" 


struct threshold_volume { 
miColor color; 
miVector center; 
miScalar radius; 
miScalar density_threshold; 
miScalar unit_density; 
miScalar march_increment ; 


i 
int threshold_volume_version(void) { return 1; } 


miBoolean threshold_volume ( 
miColor *result, miState *state, struct threshold_volume *params  ) 
| 
miScalar march_increment = *mi_eval_scalar(&params->march_increment) ; 
miColor *color = mi_eval_color(&params->color) ; 
miVector *center = mi_eval_vector(&params->center) ; 
miScalar radius = *mi_eval_scalar(&params->radius) ; 
miScalar unit_density = *mi_eval_scalar (&params->unit_density) ; 
miScalar density_threshold = *mi_eval_scalar (kparams->density_threshold) ; 
miScalar distance, accumulated_density = 0.0; 
miVector march_point, internal_center; 
mi_point_from_object(state, &internal_center, center) ; 
for (distance = 0; distance < state->dist; distance += march_increment) { 
miaux_march_point(&march_point, state, distance) ; 
accumulated_density += 
miaux_threshold_density(&march_point, &internal_center, radius, 
unit_density, march_increment) ; 
if (accumulated_density > density_threshold) { 
miaux_copy_color(result, color) ; 
break; 
} 
} 


return miTRUE; 
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declare shader 
color "density_volume" ( 
color "color" default 1i1i 1, 
vector "center" default 0 0 0, 
scalar "radius" default 1, 


scalar "unit_density" default 1, 
scalar "march_increment" default 0.1 ) 
version 1 
apply volume 
end declare 


#include "shader.h" 
#include "miaux.h" 


struct density_volume { 
miColor color; 
miVector center; 
miScalar radius; 
miScalar unit_density; 
miScalar march_increment; 


}; 
int density_volume_version(void) { return 1; } 


miBoolean density_volume ( 
miColor *result, miState *state, struct density_volume *params ) 
{ 
miScalar march_increment = *mi_eval_scalar(&params->march_increment) ; 
miColor *color = mi_eval_color(&params->color) ; 
miVector *center = mi_eval_vector(&params->center) ; 
miScalar radius = *mi_eval_scalar(&params->radius) ; 
miScalar unit_density = *mi_eval_scalar(&params->unit_density) ; 
miScalar distance, accumulated_density = 0.0; 
miVector march_point, internal_center; 
mi_point_from_object(state, &internal_center, center) ; 


for (distance = 0; distance <= state->dist; distance += march_increment) { 
miaux_march_point(&march_point, state, distance) ; 
accumulated_density += 
miaux_density_falloff(&march_point, &internal_center, radius, 
unit_density, march_increment) ; 
if (accumulated_density > 1.0) { 
accumulated_density = 1.0; 
break; 
} 
} 
if (accumulated_density > 0.0) 
miaux_blend_colors(result, result, color, 1.0 - accumulated_density) ; 


return miTRUE; 
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declare shader 
color "illuminated_volume" ( 
color "color" default 1111, 
vector "center" default 0 0 0, 
scalar "radius" default 1, 
scalar "unit_density" default 1, 


scalar "march_increment" default 0.1, 
array light "lights" ) 
version 1 
apply volume 
end declare 


#include "shader.h" 
#include "miaux.h" 


struct illuminated_volume { 
miColor color; 
miVector center; 
misScalar radius; 
miScalar unit_density; 
miScalar march_increment ; 
int i_light ; 
int n_light ; 
miTag light[1]; 

tj 


int illuminated_volume_version(void) { return 1; } 


miBoolean illuminated_volume ( 
miColor *result, miState *state, struct illuminated_volume *params ) 
{ 
miScalar radius, unit_density, march_increment, density, distance; 
miVector *center, internal_center, march_point; 
int light_count ; 
miTag *light; 


if (state->type == miRAY_LIGHT) 
return miTRUE; 


center = mi_eval_vector(&params->center) ; 

radius = *mi_eval_scalar(&params->radius) ; 

unit_density = *mi_eval_scalar(&params->unit_density) ; 
march_increment = *mi_eval_scalar (&params->march_increment) ; 
mi_point_from_object(state, &internal_center, center) ; 


if (state->type == miRAY_SHADOW) { 
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miScalar occlusion = miaux_fractional_occlusion_at_point ( 
&state->org, &state->dir, state->dist, 
&internal_center, radius, unit_density, march_increment) ; 

miaux_scale_color(result, 1.0 - occlusion) ; 

+} else { 

miColor *color = mi_eval_color(&params->color) ; 

miColor volume_color = {0,0,0,0}, light_color, point_color; 

void* original_state_pri = state->pri; 

State->pri = NULL; 

miaux_light_array(&light, &light_count, state, 

&params->i_light, &params->n_light, params->light) ; 


for (distance = 0; distance <= state->dist; distance += march_increment) { 
miaux_march_point(&march_point, state, distance) ; 
density = miaux_threshold_density ( 
&march_point, &internal_center, radius, 
unit_density, march_increment) ; 
if (density > 0.0) { 
miaux_total_light_at_point ( 

&light_color, &march_point, state, light, light_count) ; 
miaux_multiply_colors(&point_color, color, &light_color) ; 
miaux_add_transparent_color(&volume_color, &point_color, density) ; 

} 
if (volume_color.a == 1.0) 
break; 
t 
miaux_alpha_blend_colors(result, &volume_color, result); 
state->pri = original_state_pri; 


} 
return miTRUE; 
} 
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declare shader 
scalar "spherical_density" ( 
vector "center" default O 0O 0O, 


scalar "radius" default 1 ) 
version 1 
apply volume 
end declare 


#include "shader.h" 
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#include "miaux.h" 
int spherical_density_version(void) { return 1; } 


struct spherical_density { 
miVector center; 
miScalar radius; 


F3 


miBoolean spherical_density ( 
miScalar *result, miState *state, struct spherical_density *params ) 


2! 
miVector *center = mi_eval_vector(&params->center) ; 
miScalar radius = *mi_eval_scalar(&params->radius) ; 
miVector point; 
mi_vector_to_world(state, &point, &state->point) ; 
if (mi_vector_dist(center, &point) <= radius) 
*result = 1.0; 
else 
*result = 0.0; 
return miTRUE; 
} 
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declare shader 
color "parameter_volume" ( 
color "color" default i 1 1, 
shader "density_shader", 
scalar "unit_density" default 1, 


scalar "march_increment" default 0.1, 
array light "lights" ) 
version 1 
apply volume 
end declare 


#include "shader.h" 
#include "miaux.h" 


struct parameter_volume { 
miColor color; 
miTag density_shader ; 
miScalar unit_density; 
miScalar march_increment ; 
int 1_light ; 
int n_light ; 
miTag light[1]; 

I; 


int parameter_volume_version(void) { return 1; } 


miBoolean parameter_volume ( 
miColor *result, miState *state, struct parameter_volume *params  ) 
{ 


miScalar unit_density, march_increment, density; 
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miTag density_shader, *light; 
int light_count ; 


if (state->type == miRAY_LIGHT) 
return miTRUE; 


density_shader = *mi_eval_tag(&params->density_shader) ; 
unit_density = *mi_eval_scalar(&params->unit_density) ; 


march_increment = *mi_eval_scalar(&params->march_increment) ; 


miaux_light_array(&light, &light_count, state, 


B Shader source code 


&params->i_light, &params->n_light, params->light) ; 


if (state->type == miRAY_SHADOW) { 


miScalar occlusion = miaux_fractional_shader_occlusion_at_point ( 


state, &state->org, &state->dir, state->dist, 
density_shader, unit_density, march_increment) ; 
miaux_scale_color(result, 1.0 - occlusion) ; 
+ else { 
miColor *color = mi_eval_color(&params->color) ; 
miScalar distance; 


miColor volume_color = {0,0,0,0}, light_color, point_color; 


miVector original_point = state->point; 
void* original_state_pri = state->pri; 
state->pri = NULL; 


for (distance = 0; distance <= state->dist; distance += march_increment) { 


miVector march_point; 
miaux_march_point(&march_point, state, distance) ; 
state->point = march_point; 
mi_call_shader_x((miColor*) &density, 


miSHADER_MATERIAL, state, density_shader, NULL) ; 


if (density > 0) { 
density *= unit_density * march_increment ; 
miaux_total_light_at_point ( 


&light_color, &march_point, state, light, light_count) ; 
miaux_multiply_colors(&point_color, color, &light_color) ; 
miaux_add_transparent_color(&volume_color, &point_color, density) ; 


} 


if (volume_color.a == 1.0) 
break; 
} 


miaux_alpha_blend_colors(result, &volume_color, result); 


state->point = original_point; 
state->pri = original_state_pri; 
t 
return miTRUE; 
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declare shader 
scalar "radial_falloff" ( 
vector "center" default O 0 0O, 
scalar "radius" default 1, 


scalar "center_value" default i, 
scalar "radius_value" default 0O ) 
version 1 
apply volume 
end declare 


#include "shader.h" 
#include "miaux.h" 


int radial_falloff_version(void) { return 1; } 


struct radial_falloff { 
miVector center; 
miScalar radius; 
miScalar center_value; 
miScalar radius_value; 


1 


miBoolean radial_falloff ( 
miScalar *result, miState *state, struct radial_falloff *params ) 
{ 
miVector *center = mi_eval_vector(&params->center) ; 
miScalar radius = *mi_eval_scalar(&params->radius) ; 
miScalar center_value = *mi_eval_scalar(&params->center_value) ; 
miScalar radius_value = *mi_eval_scalar(&params->radius_value) ; 
miScalar distance; 
miVector point; 


mi_vector_to_world(state, &point, &state->point) ; 
distance = mi_vector_dist(center, &point) ; 
*xresult = miaux_sinusoid_fit_clamp( 

distance, 0.0, radius, center_value, radius_value) ; 


return miTRUE; 
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declare shader 
scalar "voxel_density" ( 
string "filename", 
vector "min_point" default -1 -1 -1, 


vector "max_point" default 11 1, 
color "color" default 11 1, ) 
version 1 
apply volume 
end declare 


#include "shader.h" 
#include "miaux.h" 


int voxel_dataset_version(void) { return 1; } 
#define MAX_DATASET_SIZE 400*400*400 
typedef struct { 

int width, height, depth; 


float block[MAX_DATASET_SIZE] ; 
} voxel_data; 


float voxel_value(voxel_data *voxels, float x, float y, float z) 


4. 
return voxels->blockL 
((int)(z + .5)) * voxels->depth * voxels->height + 
((int) (y + .5)) * voxels->height + 
((int) G * .5)) J; 
} 


struct voxel_density { 
miTag filename_tag; 
miVector min_point; 
miVector max_point; 
miColor color; 


}; 
int voxel_density_version(void) { return 1; } 


miBoolean voxel_density_init ( 
miState *state, struct voxel_density *params, 
miBoolean *instance_init_required) 


if (!params) { /* Main shader init (not an instance): */ 
*instance_init_required = miTRUE; 
} else { /* Instance initialization: */ 
char* filename = 
miaux_tag_to_string(*mi_eval_tag(&params->filename_tag), NULL); 
if (filename) { 
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voxel_data *voxels = 
miaux_user_memory_pointer(state, sizeof (voxel_data)) ; 

miaux_read_volume_block( 
filename, &voxels->width, &voxels->height, &voxels->depth, 
voxels->block) ; 

mi_progress("Voxel dataset: /dx/dx/d", 

voxels->width, voxels->height, voxels-—>depth) ; 
} 
r 


return miTRUE; 


miBoolean voxel_density_exit(miState *state, void *params) 


{ 


return miaux_release_user_memory("voxel_density", state, params) ; 


} 


miBoolean voxel_density ( 
miScalar *result, miState *state, struct voxel_density *params  ) 


{ 
miVector *min_point = mi_eval_vector(&params->min_point) ; 
miVector *max_point = mi_eval_vector(&params->max_point) ; 
miVector *p = &state->point; 
if (miaux_point_inside(p, min_point, max_point)) { 
float %, ¥, 2; 
voxel_data *voxels = miaux_user_memory_pointer(state, 0); 
x = miaux_fit(p->x, min_point->x, max_point->x, 0, voxels->width-1) ; 
y = miaux_fit(p->y, min_point->y, max_point->y, 0, voxels->height-1) ; 
z = miaux_fit(p->z, min_point->z, max_point->z, 0, voxels->depth-1) ; 
*result = voxel_value(voxels, x, y, Z); 
+ else 
*result = 0.0; 
return miTRUE; 
5 
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declare shader 
color "default_lens" () 
version 1 


apply lens 

scanline off 

trace on 
end declare 


574 B Shader source code 


#include "shader.h" 
int default_lens_version(void) { return 1; } 


miBoolean default_lens ( 
miColor *result, miState *state, void *params ) 


1 
return mi_trace_eye(result, state, &state->org, &state->dir) ; 
} 
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declare shader 
color "streak" ( 
scalar "max_distance" default .1 ) 
version 1 


apply lens 

scanline off 

trace on 
end declare 


#include "shader.h" 
#include "miaux.h" 


struct streak { 
miScalar max_distance; 


iy 
int streak_version(void) { return 1; } 


miBoolean streak ( 
miColor *result, miState *state, struct streak *params  ) 

! 
miScalar max_distance = *mi_eval_scalar(&params->max_distance) ; 
state->org.z += miaux_random_range(-max_distance, max_distance) ; 
return mi_trace_eye(result, state, &state->org, &state->dir) ; 
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declare shader 
color "equirectangular" () 
version 1 
apply lens 


scanline off 
trace on 
end declare 


#include "shader.h" 
#include "miaux.h" 
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int equirectangular_version(void) { return 1; } 


miBoolean equirectangular ( 
miColor *result, miState *state, void *params  ) 


| 
miMatrix matrix; 
miVector eye_ray_direction = {0, 0, -1}; 
miScalar x_fractional_position = 
state->raster_x / state->camera->x_resolution; 
miScalar y_fractional_position = 
state->raster_y / state->camera->y_resolution; 
mi_matrix_rotate( 
matrix, 
miaux_fit(y_fractional_position, 0, 1, -M_PI/2, M_PI/2), 
miaux_fit(x_fractional_position, 0, 1, M_PI, -M_PI), 
0). 
mi_vector_transform(&eye_ray_direction, keye_ray_direction, matrix); 
return mi_trace_eye(result, state, &state->org, keye_ray_direction) ; 
+ 
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declare shader 
color "fisheye" ( 
color "outside_color" default 111 ) 
version 1 


apply lens 

scanline off 

trace on 
end declare 


#include "shader.h" 
#include "miaux.h" 


struct fisheye { 
miColor outside_color; 


}; 
int fisheye_version(void) { return 1; } 


miBoolean fisheye ( 
miColor *result, miState *state, struct fisheye *params ) 
4 
miVector camera_direction; 
miScalar center_x = state->camera->x_resolution / 2.0; 
miScalar center_y = state->camera->y_resolution / 2.0; 
miScalar radius = center_x < center_y ? center_x : center_y; 
miScalar distance_from_center = 
miaux_distance(center_x, center_y, state->raster_x, state->raster_y) ; 


if (distance_from_center < radius) { 
mi_vector_to_camera(state, kcamera_direction, &state->dir) ; 
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camera_direction.z *= miaux_fit(distance_from_center, 0, radius, i, 0); 
mi_vector_normalize(&camera_direction) ; 
mi_vector_from_camera(state, &kcamera_direction, &camera_direction) ; 
return mi_trace_eye(result, state, &state->org, &camera_direction) ; 

+} else { 
*xresult = *mi_eval_color(&params->outside_color) ; 
return miTRUE; 


: 
} 
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declare shader 
color "depth_of_field" ( 
scalar "focus_plane_distance" default 1, 
scalar "blur_radius" default .1, 
integer "number_of_samples" default 1 ) 


version 1 

apply lens 

scanline off 

trace on 
end declare 


#include <stdio.h> 
#include <math.h> 

#include "shader.h" 
#include "miaux.h" 


struct depth_of_field { 
miScalar focus_plane_distance; 
miScalar blur_radius; 
miIlnteger number_of_samples; 


}; 
int depth_of_field_version(void) { return 1; } 


miBoolean depth_of_field ( 
miColor *result, miState *state, struct depth_of_field *params ) 
{ 
miScalar focus_plane_distance = 
*mi_eval_scalar (kparams->focus_plane_distance) ; 
miScalar blur_radius = 
*mi_eval_scalar(&params->blur_radius) ; 
miUint number_of_samples = 
*mi_eval_integer (&params->number_of_samples) ; 


miVector camera_origin, camera_direction, origin, direction, focus_point; 
double samples[2], focus_plane_z; 

int sample_number = 0; 

miColor sum = {0,0,0,0}, single_trace; 


miaux_to_camera_space(state, &camera_origin, &camera_direction) ; 
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focus_plane_z = state->org.z - focus_plane_distance; 
miaux_z_plane_intersect ( 
&focus_point, &camera_origin, &camera_direction, focus_plane_z) ; 


while (mi_sample(samples, &sample_number, state, 2, &number_of_samples)) { 
miaux_sample_point_within_radius ( 

&origin, &camera_origin, samples[0], samples[1], blur_radius) ; 
mi_vector_sub(&direction, &focus_point, origin) ; 
mi_vector_normalize(&direction) ; 
miaux_from_camera_space(state, origin, &direction) ; 
mi_trace_eye(&single_trace, state, &origin, &direction) ; 
miaux_add_color(&sum, &single_trace) ; 

} 
miaux_divide_color(result, &sum, number_of_samples) ; 
return miTRUE; 


t 
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declare shader 


color "phong_framebuffer" ( 
color "ambient" default 0 0 O, 
color "diffuse" a6etauit' 1-1 1, 
color "specular" default 0 0 0, 


scalar "exponent" default 30, 
array light "lights" ) 

version 1 

apply material 

end declare 


#include "shader.h" 
#include "miaux.h" 


struct phong_framebuffer { 


3 


miColor ambient; 
miColor diffuse; 
miColor specular; 
miScalar exponent ; 
int 1_light ; 
int n_light ; 
miTag light [1] ; 


int phong_framebuffer_version(void) { return 1; } 


miBoolean phong_framebuffer ( 


{ 


miColor *result, miState *state, struct phong_framebuffer *params ) 
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miColor light_color, diffuse_from_light, specular_from_light, 
diffuse_component, specular_component ; 

int 1, light_count, light_sample_count; 

miVector direction_toward_light ; 

miScalar dot_nl; 

miTag *light; 


miColor *diffuse = mi_eval_color(&params->diffuse) ; 
miColor *specular = mi_eval_color(&params->specular) ; 
miScalar exponent = *mi_eval_scalar (&params->exponent) ; 
miaux_light_array(&light, &light_count, state, 
&params->i_light, &params->n_light, params->light) ; 


xresult = *mi_eval_color(&params->ambient) ; 
miaux_set_channels(&diffuse_component, 0.0); 
miaux_set_channels(&specular_component , 0.0); 


for (i = 0; i < light_count; it+, light++) { 
miaux_set_channels(&diffuse_from_light, 0.0); 
miaux_set_channels(&specular_from_light, 0.0); 
light_sample_count = 0; 


while (mi_sample_light (&light_color, &direction_toward_light, 
&dot_nl, state, *light, &light_sample_count)) { 
miaux_add_diffuse_component ( 
&diffuse_from_light, dot_nl, diffuse, &light_color) ; 
miaux_add_phong_specular_component ( 
&specular_from_light, state, exponent, 
&direction_toward_light, specular, &light_color) ; 
} 


if (light_sample_count > 0) { 
miScalar scale_factor = 1.0 / light_sample_count; 
miaux_add_scaled_color ( 
&diffuse_component, &diffuse_from_light, scale_factor) ; 
miaux_add_scaled_color ( 
&specular_component, &specular_from_light, scale_factor) ; 
. 
t 
mi_fb_put(state, 0, &diffuse_component) ; 
mi_fb_put(state, 1, &specular_component) ; 


miaux_add_color(result, &diffuse_component) ; 
miaux_add_color(result, &specular_component) ; 


return miTRUE; 


} 
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declare shader 
color "shadowpass" ( 
color "base_color", 


array light "lights" ) 
version 1 
apply material 
end declare 


#include "shader.h" 
#include "miaux.h" 


struct shadowpass { 
miColor base_color; 
int i_light ; 
int nN L2ene ; 
miTag light[1]; 
}; 


int shadowpass_version(void) { return 1; } 


miBoolean shadowpass ( 
miColor *result, miState *state, struct shadowpass *params  ) 


{ 
int i, light_count; 
miTag *light; 
miColor without_shadow, with_shadow, shadow; 
miColor *base_color = mi_eval_color(&params->base_color) ; 
miaux_light_array(&light, &light_count, state, 
&params->i_light, &params->n_light, params->light) ; 
miaux_set_channels(&without_shadow, 0.0); 
miaux_set_channels(&with_shadow, 0.0); 
for (i = 0; i < light_count; i++, light++) { 
miaux_add_light_color(&without_shadow, state, *light, miFALSE) ; 
miaux_add_light_color(&with_shadow, state, *light, miTRUE) ; 
} 
miaux_divide_colors(&shadow, &with_shadow, &without_shadow) ; 
miaux_multiply_colors(result, base_color, &shadow) ; 
mi_fb_put(state, 0, base_color); 
mi_fb_put(state, 1, &shadow) ; 
return miTRUE; 
} 
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declare shader 
color "framebuffer_put" ( 
color “color", 
integer "index" ) 


version 1 
apply material 
end declare 


#include "shader.h" 


struct framebuffer_put { 
miColor color; 
milnteger index; 


3 


int framebuffer_put_version(void) { return(1); } 


miBoolean framebuffer_put ( 
miColor *result, miState *state, struct framebuffer_put *params ) 


‘ 
*xresult = *mi_eval_color(&params->color) ; 
if (state->type == miRAY_EYE) 
mi_fb_put(state, *mi_eval_integer(&params->index), result) ; 
return miTRUE; 
} 
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declare shader 
color "add_colors" ( 
color "x". 


color "y" ) 
apply material 
version 1 
end declare 


#include "shader.h" 


struct add_colors { 
miColor x; 
miColor y; 


Fi 
int add_colors_version(void) { return 1; } 
miBoolean add_colors ( 


miColor *result, miState *state, struct add_colors *params ) 


{ 


miColor *x = mi_eval_color(&params->x) ; 
miColor *y = mi_eval_color(&params->y) ; 


result->r = x->r + y->r; 
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result->g = x->g + y->g; 
result->b = x->b + y->b; 


return miTRUE; 
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declare shader 
color "letterbox" ( 
scalar "aspect_ratio" default 1.85, 
color "outside_scale" default 000 ) 


version 1 
apply output 
end declare 


#include "shader.h" 
#include "miaux.h" 
#include <stdlib.h> 


struct letterbox { 
miScalar aspect_ratio; 
miColor outside_scale; 


si 
int letterbox_version(void) { return 1; } 


miBoolean letterbox ( 
void *result, miState *state, struct letterbox *params ) 

{ 
int x, ¥3 
miColor pixel; 
miScalar aspect_ratio = *mi_eval_scalar(&params->aspect_ratio) ; 
miColor *xoutside_scale = mi_eval_color(&params->outside_scale) ; 
miScalar image_width = state->camera->x_resolution; 
miScalar image_height = state->camera->y_resolution; 
miScalar letterbox_height = image_width / aspect_ratio; 
miScalar y_min = (image_height - letterbox_height) / 2.0; 
miScalar y_max = image_height - y_min; 


milmg_image *fb = mi_output_image_open(state, miRC_IMAGE_RGBA) ; 


for (y = 0; y < state->camera->y_resolution; y++) { 
if (mi_par_aborted() ) 
break; 
for (x = 0; x < state->camera->x_resolution; xt++) { 
mi_img_get_color(fb, &pixel, x, y); 
if (y < y_min || y > y_max) f 
miaux_multiply_colors(&pixel, &pixel, outside_scale) ; 
mi_img_put_color(fb, &pixel, x, y); 


} 
} 
mi_output_image_close(state, miRC_IMAGE_RGBA) ; 


return miTRUE; 
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miaux_multiply_colors 593 
median filter Page 445 


declare shader 
color "median_filter" ( 
integer "radius" default 1 ) 


version 1 
apply output 
end declare 


#include "shader.h" 
#include "miaux.h" 
#include <stdlib.h> 


struct median filter { 
miInteger radius; 


if 
int median_filter_version(void) { return 1; } 


miBoolean median_filter ( 
void *result, miState *state, struct median_filter *params ) 
{ 
miColor *neighbors; 
int radius = *mi_eval_integer(&params->radius), x, y, 
kernel_size = (radius * 2 + 1) * (radius * 2 + 1), 
middle = kernel_size / 2; 


milmg_image *fb_input = mi_output_image_open(state, miRC_IMAGE_RGBA) ; 
milmg_image *fb_output = mi_output_image_open(state, miRC_IMAGE_USER) ; 


neighbors = (miColor*) mi_mem_allocate(kernel_size * sizeof(miColor)) ; 
for (y = 0; y < state->camera->y_resolution; yt++) { 
if (mi_par_aborted() ) 
break; 
for (x = 0; x < state->camera->x_resolution; xt++) { 
miaux_pixel_neighborhood(neighbors, fb_input, x, jy, radius) ; 
qsort(neighbors, kernel_size, sizeof(miColor), 
miaux_color_compare) ; 
mi_img_put_color(fb_output, &neighbors[middle], x, y); 
I 
} 


mi_mem_release (neighbors) ; 


mi_output_image_close(state, miRC_IMAGE_RGBA) ; 
mi_output_image_close(state, miRC_IMAGE_USER) ; 


return miTRUE; 
Function Page 
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annotate Page 451 


declare shader 
color "annotate" ( 
string "text", 
string "fontimage_filename", 
integer "x" default 10, 


integer "y" default 10, 
color "color" default 111 ) 
version 1 
apply output 
end declare 


#include "shader.h" 
#include "miaux.h" 


struct annotate { 
miTag text; 
miTag fontimage_filename; 
milnteger x; 
miInteger y; 
miColor color; 


Fi; 
int annotate_version(void) { return 1; } 


miBoolean annotate ( 
void *result, miState *state, struct annotate *params ) 
‘ 
if (params->text != miNULLTAG) { 
int x, y, t_x, t_y, t_width, t_height; 
float *text_image; 
milmg_image *fb; 
fontimage fimage; 
miColor *text_color = mi_eval_color(&params->color), pixel_color; 
char* text = miaux_tag_to_string( 
*mi_eval_tag(&params->text), NULL); 
int p_x = *mi_eval_integer(&params->x) , 
p_y = *mi_eval_integer (&params->y) ; 
char* fontimage_filename = 
miaux_tag_to_string(*mi_eval_tag(&params->fontimage_filename) , 
"Courier-Bold_24.fontimage") ; 


miaux_load_fontimage(&fimage, fontimage_filename) ; 
miaux_text_image(&text_image, &t_width, &t_height, &fimage, text); 


fb = mi_output_image_open(state, miRC_IMAGE_RGBA) ; 
for (y = p_y, t_y = 0; t_y < t_height; yt++, t_yt+) { 
if (mi_par_aborted()) { 
mi_progress ("Abort") ; 
break; 


for (x = px, tx = 0; tix < tiwidth; x4+, tiz++) { 
float alpha = text_image[t_y * t_width + t_x]; 
mi_img_get_color(fb, &pixel_color, x, y); 
miaux_alpha_blend(&pixel_color, text_color, alpha); 
mi_img_put_color(fb, &pixel_color, x, y); 


ty 
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} 


miaux_release_fontimage(&fimage) ; 
mi_output_image_close(state, miRC_IMAGE_RGBA) ; 


t 
return miTRUE; 
} 

Function Page 
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The miaux utility library 


The description of the miaux utility functions in the text are also listed in the index under the 
topic “utility functions.” 


Utility header file miaux.h 
/* 


"Writing mental ray shaders" -- Utility functions used in shaders 
See http://www.writingmentalrayshaders.com/ for the current software distribution 


* / 


#ifndef __MIAUX_H__ 
#define __MIAUX_H__ 


#include <stdlib.h> 
#include <stdio.h> 
#include <stdarg.h> 
#include <unistd.h> 
#include <string.h> 
#include <math.h> 
#include <sys/types.h> 
#include "shader.h" 
#include "geoshader.h" 


typedef struct { 
miScalar x; 
miScalar jy; 
miScalar Zz; 
miScalar r; 

} miaux_sphere_spec; 


typedef void (*miaux_bbox_function) (midbject*, void*) ; 


typedef struct { 
int width; 
int height ; 
int *x_offsets; 
unsigned char *image; 
} fontimage; 


double miaux_fit( 

double v, double oldmin, double oldmax, double newmin, double newmax) ; 
double miaux_blend(miScalar a, miScalar b, miScalar factor); 
void miaux_blend_colors(miColor *result, 

miColor *colori, miColor *color2, miScalar factor); 
void miaux_blend_channels(miColor *result, 
miColor *blend_color, miColor *blend_fraction) ; 

void miaux_invert_channels(miColor *result, miColor *color) ; 
miBoolean miaux_all_channels_equal(miColor *c, miScalar v); 
void miaux_scale_vector(miVector *result, miScalar scale) ; 
void miaux_set_vector(miVector *v, double x, double y, double z); 
double miaux_summed_noise ( 

miVector *point, 

double summing_weight, double octave_scaling, int octave_count) ; 
char* miaux_tag_to_string(miTag tag, char *default_value) ; 
void miaux_add_scaled_color(miColor *result, miColor *color, miScalar scale) ; 
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miScalar miaux_quantize(miScalar value, miInteger count) ; 
void miaux_add_diffuse_component ( 

miColor *result, 

miScalar light_and_surface_cosine, 

miColor *diffuse, miColor *light_color) ; 
void miaux_set_channels(miColor *c, miScalar new_value) ; 
void miaux_light_array(miTag **lights, int *light_count, miState *state, 

int *offset_param, int *count_param, miTag *lights_param) ; 

miScalar miaux_light_spread(miState *state, miTag light_tag) ; 
miScalar miaux_offset_spread_from_light (miState *state, milag light_tag) ; 
miTag miaux_current_light_tag(miState *state) ; 
void miaux_scale_color(miColor *result, miScalar scale) ; 
double miaux_sinusoid_fit( 

double v, double oldmin, double oldmax, double newmin, double newmax) ; 
void miaux_add_phong_specular_component ( 

miColor *result, miState *state, miScalar exponent, 

miVector *direction_toward_light, 

miColor *specular, miColor *light_color) ; 
void miaux_add_blinn_specular_component ( 

miColor *result, miState *state, 

miScalar roughness, miScalar ior, 

miVector direction_toward_light, 

miColor *specular, miColor *light_color) ; 
void miaux_add_cook_torrance_specular_component ( 

miColor *result, miState *state, 

miScalar roughness, miColor *ior, 

miVector direction_toward_light, 

miColor *specular, miColor *light_color) ; 
void miaux_add_ward_specular_component ( 

miColor *result, miState *state, 

miScalar shiny_u, miScalar shiny_v, 

miColor *glossy, miScalar normal_dot_light, 

miVector direction_toward_light, 

miColor *light_color) ; 
void miaux_add_color(miColor *result, miColor *c); 
void miaux_multiply_colors(miColor *result, miColor *x, miColor *y); 
void miaux_scale_channels(miColor *result, miColor* color, 

miScalar r_scale, miScalar g_scale, miScalar b_scale) ; 

double miaux_fit_clamp( 

double v, double oldmin, double oldmax, double newmin, double newmax) ; 
double miaux_sinusoid_fit_clamp( 

double v, double oldmin, double oldmax, double newmin, double newmax); 
void miaux_add_mock_specular_component ( 

miColor *result, miState *state, 

miVector *direction_toward_light, 

miColor *specular_color, 

miColor *cutoff, 

miColor *light_color) ; 
void miaux_brighten_rim(miColor *result, miState *state, 

miColor *rim_color) ; 

double miaux_shadow_breakpoint ( 

double color, double transparency, double breakpoint ); 
double miaux_shadow_breakpoint_scale ( 

double color, double transparency, double breakpoint, 

double center, double extent ); 
double miaux_shadow_continuous ( 

double color, double transparency, double expansion ); 
miBoolean miaux_ray_is_entering_material(miState *state) ; 
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miScalar miaux_state_incoming_ior(miState *state) ; 
miScalar miaux_state_outgoing_ior(miState *state) ; 
miBoolean miaux_shaders_equal(miState *s1, miState *s2) ; 
miBoolean miaux_parent_exists(miState *state) ; 
miBoolean miaux_ray_is_transmissive(miState *state) ; 
miBoolean miaux_ray_is_entering( 
miState *state, 
miState *state_of_this_shaders_previous_transmission) ; 
void miaux_set_state_refraction_indices(miState *state, 
miScalar material_ior) ; 
void miaux_add_multiplied_colors(miColor *result, 
miColor *color, miColor *scaling_color) ; 
void miaux_multiply_color(miColor *result, miColor *color) ; 
void miaux_set_scalar_if_not_default ( 
miScalar *result, miState *state, miScalar *param) ; 
void miaux_set_integer_if_not_default ( 
miInteger *result, miState *state, miInteger *param) ; 
double miaux_sinusoid(double v, double frequency, double amplitude) ; 
miScalar miaux_color_channel_average(miColor *c) ; 
void miaux_add_vertex(int index, miScalar x, miScalar y, miScalar z); 
float miaux_random_range(float min_value, float max_value) ; 
void miaux_random_point_in_unit_sphere(float *x, float *y, float *z); 
void miaux_add_random_triangle(int index, float edge_length_max, 
miVector *bbox_min, miVector *bbox_max) ; 
miTag miaux_object_from_file( 
const char* name, const char* filename, 
miVector bbox_min, miVector bbox_max) ; 
void miaux_define_hair_object( 
miTag name_tag, miaux_bbox_function bbox_function, void *params, 
miTag *geoshader_result, miApi_object_callback callback) ; 
void miaux_describe_bbox(mi0bject *obj); 
void miaux_adjust_bbox(mi0bject *obj, miVector *v, miScalar extra) ; 
void miaux_init_bbox(mi0bject *obj); 
void miaux_append_hair_vertex(miScalar **scalar_array, miVector *v); 
void miaux_append_hair_data( 
miScalar **scalar_array, miVector *v, miScalar position, 
miScalar root_radius, miColor *root, miScalar tip_radius, miColor *tip ); 
double miaux_max(double a, double b); 
void miaux_copy_color(miColor *result, miColor *color) ; 
void miaux_opacity_set_channels(miState *state, miScalar value) ; 
void miaux_add_transparent_hair_component(miColor *result, miState *state) ; 
void miaux_add_specular_hair_component ( 
miColor *result, miVector *hair_tangent, miVector *to_light, 
miVector *to_camera, 
miColor *specular, miColor *light_color) ; 
void miaux_add_diffuse_hair_component ( 
miColor *result, miVector *hair_tangent, miVector *to_light, 
miColor *diffuse, miColor *light_color) ; 
double miaux_clamp(double v, double minval, double maxval) ; 
void miaux_clamp_color(miColor *result) ; 
void miaux_point_between ( 
miVector *result, miVector *u, miVector *v, float fraction) ; 
void miaux_perpendicular_point(miVector *result, miVector *v, float distance) ; 
void miaux_hair_spiral ( 
miScalar** scalar_array, miVector *start_point, miVector *end_point, 
float turns, int point_count, float angle_offset, float spiral_radius, 
miScalar root_radius, miScalar tip_radius) ; 
void miaux_random_point_on_sphere ( 
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miVector *result, miVector *center, miScalar radius) ; 
void miaux_read_hair_data_file(char* filename, miScalar radius) ; 
void miaux_hair_data_file_bounding_box( 
char* filename, 
float *xmin, float *ymin, float *zmin, 
float *xmax, float *ymax, float *zmax) ; 
void miaux_blend_transparency(miColor *result, 
miState *state, miColor *transparency) ; 
void miaux_color_fit(miColor *result, 
miScalar f, miScalar start, miScalar end, 
miColor *start_color, miColor *end_color) ; 
miScalar miaux_interpolated_lookup(miScalar lookup_table[], int table_size, 
miScalar t); 
float miaux_altitude(miState *state); 
void miaux_piecewise_sinusoid( 
miScalar result[], int result_count, 
int key_count, miScalar key_positions[], miScalar key_values[]); 
miBoolean miaux_release_user_memory (char* shader_name, miState *state, void *params) ; 
void* miaux_user_memory_pointer(miState *state, int allocation_size) ; 
void miaux_interpolated_color_lookup(miColor* result, 
miColor lookup_table[], int table_size, 
miScalar. t): 
void miaux_piecewise_color_sinusoid( 
miColor result[], int result_count, int key_count, miColor key_values[]); 
void miaux_point_along_vector( 
miVector *result, miVector *point, miVector *direction, miScalar distance) ; 
void miaux_march_point ( 
miVector *result, miState *state, miScalar distance) ; 
void miaux_world_space_march_point ( 
miVector *result, miState *state, miScalar distance) ; 
miScalar miaux_threshold_density ( 
miVector *point, miVector *center, miScalar radius, 
miScalar unit_density, miScalar march_increment) ; 
miScalar miaux_density_falloff ( 
miVector *point, miVector *center, miScalar radius, 
miScalar unit_density, miScalar march_increment) ; 
void miaux_alpha_blend_colors( 
miColor *result, miColor *foreground, miColor *background) ; 
void miaux_add_transparent_color( 
miColor *result, miColor *color, miScalar transparency) ; 
void miaux_total_light_at_point ( 
miColor *result, miVector *point, miState *state, 
miTag* light, int light_count) ; 
miScalar miaux_fractional_occlusion_at_point ( 
miVector *start_point, miVector *direction, 
miScalar total_distance, miVector *center, miScalar radius, 
miScalar unit_density, miScalar march_increment) ; 
miScalar miaux_fractional_shader_occlusion_at_point ( 
miState *state, miVector *start_point, miVector *direction, 
miScalar total_distance, miTag density_shader, 
miScalar unit_density, miScalar march_increment) ; 
miBoolean miaux_point_inside(miVector *p, miVector *min_p, miVector *max_p) ; 
void miaux_read_volume_block( 
char* filename, 
int *width, int *height, int *depth, float* block); 
double miaux_distance(double x1, double y1, double x2, double y2); 
void miaux_divide_color(miColor *result, miColor* color, miScalar f); 
void miaux_from_camera_space ( 
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miState *state, miVector *origin, miVector *direction) ; 

void miaux_square_to_circle( 

float *result_x, float *result_y, float x, float y, float max_radius) ; 
void miaux_sample_point_within_radius ( 

miVector *result, miVector *center, float x, float y, float max_radius) ; 
void miaux_z_plane_intersect ( 

miVector *result, miVector *origin, miVector *direction, miScalar z_plane) ; 
void miaux_to_camera_space ( 

miState *state, miVector *origin, miVector *direction) ; 
void miaux_divide_colors(miColor *result, miColor *x, miColor *y); 
void miaux_add_light_color( 

miColor *result, miState *state, miTag light, char shadow_state) ; 
int miaux_color_compare(const void *vx, const void *vy); 
void miaux_pixel_neighborhood( 

miColor *neighbors, 

miImg_image *buffer, int x, int y, int radius); 
void miaux_release_fontimage(fontimage *fimage) ; 
void miaux_alpha_blend(miColor *x, miColor *y, miScalar alpha) ; 
void miaux_text_image ( 

float **text_image, int *width, int *height, 

fontimage *fimage, char* text); 
void miaux_load_fontimage(fontimage *fimage, char* filename) ; 
#endif 


Utility source file miaux.c 
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The functions in miaux.c are divided into sections based on the first chapter in which the function 


is used. 


#include "miaux.h" 


Chapter 7 — Color from position 


double miaux_fit ( 
double v, double oldmin, double oldmax, double newmin, double newmax) 


1, 
return newmin + ((v - oldmin) / (oldmax - oldmin)) * (mewmax - newmin); 
} 
double miaux_blend(miScalar a, miScalar b, miScalar factor) 
{ 
return a * factor + b * (1.0 - factor); 
} 


void miaux_blend_colors(miColor *result, 
miColor *colori, miColor *color2, miScalar factor) 


{ 
result->r = miaux_blend(colori->r, color2->r, factor); 
result->g = miaux_blend(colori->g, color2->g, factor) ; 
result->b = miaux_blend(colori->b, color2->b, factor); 
} 


Chapter 8 — The transparency of a surface 


void miaux_blend_channels(miColor *result, 
miColor *blend_color, miColor *blend_fraction) 
{ 
result->r = miaux_blend(result->r, blend_color->r, blend_fraction->r) ; 
result->g = miaux_blend(result->g, blend_color->g, blend_fraction->g) ; 
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result->b = miaux_blend(result->b, blend_color->b, blend_fraction->b) ; 


} 


void miaux_invert_channels(miColor *result, miColor *color) 


{ 


result->r = 1.0 - color->r; 
result->g = 1.0 - color->g; 
result->b = 1.0 - color->b; 
result->a = 1.0 - color->a; 


} 


miBoolean miaux_all_channels_equal(miColor *c, miScalar v) 
{ 
if (c->r == v && c->g == v && c->b == v && c->a == v) 
return miTRUE; 
else 
return miFALSE; 


Chapter 9 — Color from functions 


void miaux_scale_vector(miVector *result, miScalar scale) 
{ 

result->x *= scale; 

result->y *= scale; 

result->z *= scale; 


} 


void miaux_set_vector(miVector *v, double x, double y, double z) 


{ 


V->xX = X; 
vV->y = ¥; 
V->Z = Z; 


} 


double miaux_summed_noise ( 
miVector *point, 
double summing_weight, double octave_scaling, int octave_count) 


imc 1; 
double noise_value, 
noise_sum = 0.0, noise_scale = 1.0, maximum_noise_sum = 0.0; 
miVector scaled_point; 
miaux_set_vector(&scaled_point, point->x, point->y, point->z) ; 


for (i = 0; i < octave_count; i++) { 
noise_value = mi_unoise_3d(&scaled_point) ; 
noise_sum += noise_value / noise_scale; 
maximum_noise_sum += 1.0 / noise_scale; 
noise_scale *= summing_weight; 
miaux_scale_vector(&scaled_point, octave_scaling) ; 
} 


return noise_sum/maximum_noise_sum; 


Chapter 10 — The color of edges 


char* miaux_tag_to_string(miTag tag, char *default_value) 
{ 
char *result = default_value; 
if (tag != 0) { 
result = (char*)mi_db_access (tag) ; 
mi_db_unpin(tag) ; 
} 


return result; 
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} 


void miaux_add_scaled_color(miColor *result, miColor *color, miScalar scale) 
{ 

result->r += color->r * scale; 

result->g += color->g * scale; 

result->b += color->b * scale; 


t 
miScalar miaux_quantize(miScalar value, miInteger count) 
{ 
miScalar q = (miScalar) count; 
if (count < 2) 
return q; 
else 
return (miScalar) ((int) (value * q) / (q - 1)); 
t 


void miaux_add_diffuse_component ( 
miColor *result, 
miScalar light_and_surface_cosine, 
miColor *diffuse, miColor *light_color) 


1 
result->r += light_and_surface_cosine * diffuse->r * light_color->r; 
result->g += light_and_surface_cosine * diffuse->g * light_color->g; 
result->b += light_and_surface_cosine * diffuse->b * light_color->b; 
t 
void miaux_set_channels(miColor *c, miScalar new_value) 
{ 
C->r = c->g = c->b = c->a = new_value; 
t 


void miaux_light_array(miTag **lights, int *light_count, miState *state, 
int *offset_param, int *count_param, miTag *lights_param) 


{ 
int array_offset = *mi_eval_integer(offset_param) ; 
*xlight_count = *mi_eval_integer(count_param) ; 
*lights = mi_eval_tag(lights_param) + array_offset; 
} 


Chapter 11 — Lights 


miScalar miaux_light_spread(miState *state, miTag light_tag) 


{ 
miScalar light_spread; 
mi_query(miQ_LIGHT_SPREAD, state, light_tag, &light_spread) ; 
return light_spread; 

r 


miScalar miaux_offset_spread_from_light(miState *state, miTag light_tag) 
| 
miVector light_direction, light_to_sample_point; 


mi_query(miQ_LIGHT_DIRECTION, state, light_tag, &light_direction) ; 
mi_vector_normalize(&light_direction) ; 


mi_vector_to_light(state, &light_to_sample_point, &state->dir) ; 
mi_vector_normalize(&light_to_sample_point) ; 


return mi_vector_dot(&light_to_sample_point, &light_direction) ; 


} 


miTag miaux_current_light_tag(miState *state) 


miTag light_tag; 
mi_query(miQ_INST_ITEM, state, state->light_instance, &light_tag) ; 
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return light_tag; 


} 
void miaux_scale_color(miColor *result, miScalar scale) 
{ 
result->r *= scale; 
result->g *= scale; 
result->b *= scale; 
} 


double miaux_sinusoid_fit( 
double v, double oldmin, double oldmax, double newmin, double newmax) 


{ 
return miaux_fit(sin(miaux_fit(v, oldmin, oldmax, -M_PI_2, M_PI_2)), 
“ly ly 
newmin, newmax) ; 
} 


Chapter 12 — Light on a surface 


void miaux_add_phong_specular_component ( 
miColor *result, miState *state, miScalar exponent, 
miVector *direction_toward_light, 
miColor *specular, miColor *light_color) 


1. 
miScalar specular_amount = 
mi_phong_specular(exponent, state, direction_toward_light) ; 
if (specular_amount > 0.0) { 
result->r += specular_amount * specular->r * light_color->r; 
result->g += specular_amount * specular->g * light_color->g; 
result->b += specular_amount * specular->b * light_color->b; 
} 
t 


void miaux_add_blinn_specular_component ( 
miColor *result, miState *state, 
miScalar roughness, miScalar ior, 
miVector direction_toward_light, 
miColor *specular, miColor *light_color) 


{ 
miScalar specular_amount = 
mi_blinn_specular(&state->dir, &direction_toward_light, 
&state->normal, roughness, ior); 
if (specular_amount > 0.0) { 
result->r += specular_amount * specular->r * light_color->r; 
result->g += specular_amount * specular->g * light_color->g; 
result->b += specular_amount * specular->b * light_color->b; 
h 
} 


void miaux_add_cook_torrance_specular_component ( 
miColor *result, miState *state, 
miScalar roughness, miColor *ior, 
miVector direction_toward_light, 
miColor *specular, miColor *light_color) 


{ 
miColor specular_reflection_color; 
if (mi_cooktorr_specular (&specular_reflection_color, &state->dir, 
&direction_toward_light, 
&state->normal, roughness, ior)) { 
result->r += specular_reflection_color.r * specular->r * light_color->r; 
result->g += specular_reflection_color.g * specular->g * light_color->g; 
result->b += specular_reflection_color.b * specular->b * light_color->b; 
t; 
} 


void miaux_add_ward_specular_component ( 
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miColor *result, miState *state, 

miScalar shiny_u, miScalar shiny_v, 
miColor *glossy, miScalar normal_dot_light, 
miVector direction_toward_light, 

miColor *light_color) 


t 
miScalar specular_reflection_amount; 
if (shiny_u == shiny_v) /* Isotropic */ 
specular_reflection_amount = normal_dot_light * 
mi_ward_glossy( 
&state->dir, &direction_toward_light, &state->normal, shiny_u) ; 
else { /* Anisotropic */ 
miVector u = state->derivs[0], v; 
float d = mi_vector_dot(&u, &state->normal) ; 
u.x -= d * state->normal.x; 
u.y -= d * state->normal.y; 
u.z -= d * state->normal.z; 
mi_vector_normalize(&u) ; 
/* Set v to be perpendicular to u (in the tangent plane) */ 
mi_vector_prod(&v, &state->normal, &u); 
specular_reflection_amount = normal_dot_light * 
mi_ward_anisglossy(&state->dir, &direction_toward_light, 
&state->normal, &u, &v, shiny_u, shiny_v); 
} 
if (specular_reflection_amount > 0.0) { 
result->r += specular_reflection_amount * glossy->r * light_color->r; 
result->g += specular_reflection_amount * glossy->g * light_color->g; 
result->b += specular_reflection_amount * glossy->b * light_color->b; 
f 
} 
void miaux_add_color(miColor *result, miColor *c) 
+ 
result->r += c->r; 
result->g += c->g; 
result->b += c=->b; 
result->a += c->a; 
, 


void miaux_multiply_colors(miColor *result, miColor *x, miColor *y) 
! 

result->r = x->r * y->r; 

result->g x->g * y->g; 

result->b = x->b * y->b; 


} 


void miaux_scale_channels(miColor *result, miColor* color, 
miScalar r_scale, miScalar g_scale, miScalar b_scale) 


{ 
result->r = color->r * r_scale; 
result->g = color->g * g_scale; 
result->b = color->b * b_scale; 
} 


double miaux_fit_clamp( 
double v, double oldmin, double oldmax, double newmin, double newmax) 
{ 
if (oldmin > oldmax) { 
double temp = oldmin; 
oldmin = oldmax; 
oldmax = oldmin; 
temp = newmin; 
newmin = newmax; 
newmax = newmin; 
F 
if (v < oldmin) 
return newmin; 
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else if (v > oldmax) 
return newmax; 
else 
return miaux_fit(v, oldmin, oldmax, newmin, newmax) ; 


} 


double miaux_sinusoid_fit_clamp( 
double v, double oldmin, double oldmax, double newmin, double newmax) 
{ 
return miaux_fit(sin(miaux_fit_clamp(v, oldmin, oldmax, -M_PI_2, M_PI_2)), 
-1, 1, newmin, newmax); 


} 


void miaux_add_mock_specular_component ( 
miColor *result, miState *state, 
miVector *direction_toward_light, 
miColor *specular_color, 
miColor *cutoff, 
miColor *light_color) 


{ 
miScalar lightdir_offset, r_scale, g_scale, b_scale; 
miColor attenuated_specular = {0,0,0,0}; 
lightdir_offset = mi_vector_dot(&state->normal, direction_toward_light) ; 
r_scale = miaux_sinusoid_fit_clamp(lightdir_offset, cutoff->r, 1.0, 0, 1); 
g_scale = miaux_sinusoid_fit_clamp(lightdir_offset, cutoff->g, 1.0, 0, 1); 
b_scale = miaux_sinusoid_fit_clamp(lightdir_offset, cutoff->b, 1.0, 0, 1); 
miaux_scale_channels(&attenuated_specular, specular_color, 

r_scale, g_scale, b_scale) ; 

miaux_multiply_colors(light_color, light_color, &attenuated_specular) ; 
miaux_add_color(result, light_color) ; 

} 


void miaux_brighten_rim(miColor *result, miState *state, 
miColor *rim_color) 


{ 
miaux_add_scaled_color(result, rim_color, 1.0 + state->dot_nd) ; 


} 


Chapter 13 — Shadows 


double miaux_shadow_breakpoint ( 
double color, double transparency, double breakpoint ) 


{ 
if (transparency < breakpoint) 
return miaux_fit(transparency, 0, breakpoint, 0, color); 
else 
return miaux_fit(transparency, breakpoint, 1, color, 1); 
} 


double miaux_shadow_breakpoint_scale ( 
double color, double transparency, double breakpoint, 
double center, double extent ) 


{ 
double scaled_color = 
miaux_fit(color, 0, 1, center - extent/2.0, center + extent/2.0); 
if (transparency < breakpoint) 
return miaux_fit(transparency, 0, breakpoint, 0, scaled_color) ; 
else 
return miaux_fit(transparency, breakpoint, 1, scaled_color, 1); 
} 


double miaux_shadow_continuous ( 
double color, double transparency, double expansion ) 
{ 


return transparency 
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+ miaux_fit (transparency, 
0, i, 


expansion * transparency * (color - transparency), 0); 


Chapter 15 — Refraction 


miBoolean miaux_ray_is_entering_material(miState *state) 
vf 

miState *s; 

miBoolean entering = miTRUE; 

for (s = state; s != NULL; s = s->parent) 


if (s->material == state->material) 
entering = !entering; 
return entering; 
t 
miScalar miaux_state_incoming_ior(miState *state) 
i 
miScalar unassigned_ior = 0.0, default_ior = 1.0; 
if (state != NULL && state->ior_in != unassigned_ior) 
return state->ior_in; 
else 
return default_ior; 
5 
miScalar miaux_state_outgoing_ior(miState *state) 
{ 
miScalar unassigned_ior = 0.0, default_ior = 1.0; 
if (state != NULL && state->ior != unassigned_ior) 
return state->ior; 
else 
return default_ior; 
t 


miBoolean miaux_shaders_equal(miState *si, miState *s2) 


{ 


return si->shader == s2->shader; 
: 
miBoolean miaux_parent_exists(miState *state) 
{ 
return state->parent != NULL; 
t 
miBoolean miaux_ray_is_transmissive(miState *state) 
{ 
return state->type == miRAY_TRANSPARENT | | 
state->type == miRAY_REFRACT; 
} 


miBoolean miaux_ray_is_entering( 
miState *state, 
miState *state_of_this_shaders_previous_transmission) 


miState *s; 
miBoolean ray_is_entering = miTRUE; 
state_of_this_shaders_previous_transmission = NULL; 
for (s = state; s; s = s->parent) 
if (miaux_ray_is_transmissive(s) && 
miaux_parent_exists(s) && 
miaux_shaders_equal(s->parent, state)) { 
ray_is_entering = !ray_is_entering; 
if (state_of_this_shaders_previous_transmission == NULL) 


state_of_this_shaders_previous_transmission = s->parent; 


} 


return ray_is_entering; 
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} 


void miaux_set_state_refraction_indices(miState *state, 
miScalar material_ior) 


{ 
miState *previous_transmission = NULL; 
miScalar incoming_ior, outgoing_ior; 
if (miaux_ray_is_entering(state, previous_transmission)) { 
outgoing_ior = material_ior; 
incoming_ior = miaux_state_outgoing_ior(state->parent) ; 
} else { 
incoming_ior = material_ior; 
outgoing ior = miaux_state_incoming_ior(previous_transmission) ; 
state->ior_in = incoming_ior; 
state->ior = outgoing_ior; 
} 


Chapter 16 — Light from other surfaces 


void miaux_add_multiplied_colors(miColor *result, 
miColor *color, miColor *scaling_color) 


sf 
result->r += color->r * scaling_color->r; 
result->g += color->g * scaling color->g; 
result->b += color->b * scaling color->b; 
} 


void miaux_multiply_color(miColor *result, miColor *color) 
{ 

result->r *= color->r; 

result->g *= color->g; 

result->b *= color->b; 


} 


void miaux_set_scalar_if_not_default( 
miScalar *result, miState *state, miScalar *param) 


{ 
miScalar use_default_flag = -1.0; 
miScalar param_value = *mi_eval_scalar (param) ; 
if (param_value != use_default_flag) 
*result = param_value; 
J 


void miaux_set_integer_if_not_default ( 
miInteger *result, miState *state, milnteger *param) 


{ 
miInteger use_default_flag = -1; 
miInteger param_value = *mi_eval_integer (param) ; 
if (param_value != use_default_flag) 
*result = param_value; 
r 


Chapter 17 — Modifying surface geometry 


double miaux_sinusoid(double v, double frequency, double amplitude) 


q 
} 


return sin(v * frequency * M_PI * 2.0) * amplitude; 


Chapter 18 — Modifying surface orientation 


miScalar miaux_color_channel_average(miColor *c) 


B Shader source code 
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returm (c-or + c->e + G->b) / 3.0; 


Chapter 19 — Creating geometric objects 


void miaux_add_vertex(int index, miScalar x, miScalar y, miScalar z) 
4 

miVector v; 

V.X =X; V.y = y; v.z = Z; 

mi_api_vector_xyz_add (kv) ; 

mi_api_vertex_add (index) ; 


} 


float miaux_random_range(float min_value, float max_value) 


{ 
} 


return miaux_fit(mi_random(), 0.0, 1.0, min_value, max_value) ; 


void miaux_random_point_in_unit_sphere(float *x, float *y, float *z) 


{ 


do { 
*x = miaux_random_range(-.5, .5); 
*y = miaux_random_range(-.5, .5); 
*z = miaux_random_range(-.5, .5); 


} while (sqrt((*x * *x) +(*y * *y) + (#z * *z)) >= 0.5); 
} 


void miaux_add_random_triangle(int index, float edge_length_max, 
miVector *bbox_min, miVector *bbox_max) 


{ 

int vertex_index; 

float offset_max = edge_length_max / 2.0; 

float offset_min = -offset_max; 

float x, y, Z; 

miaux_random_point_in_unit_sphere(&x, &y, &z); 

x = miaux_fit(x, -.5, .5, bbox_min->x, bbox_max->x) ; 

y = miaux_fit(y, -.5, .5, bbox_min->y, bbox_max->y) ; 

Zz = miaux_fit(z, -.5, .5, bbox_min->z, bbox_max->z) ; 

miaux_add_vertex(index, x, y, Z); 

miaux_add_vertex(index + 1, 
x + miaux_random_range(offset_min, offset_max), 
y + miaux_random_range(offset_min, offset_max), 
z + miaux_random_range(offset_min, offset_max)); 

miaux_add_vertex(index + 2, 
x + miaux_random_range(offset_min, offset_max), 
y + miaux_random_range(offset_min, offset_max), 
z + miaux_random_range(offset_min, offset_max)) ; 

mi_api_poly_begin_tag(1, 0); 

for (vertex_index = 0; vertex_index < 3; vertex_index++) 

mi_api_poly_index_add(index + vertex_index) ; 
mi_api_poly_end() ; 
} 


miTag miaux_object_from_file( 
const char* name, const char* filename, 
miVector bbox_min, miVector bbox_max) 


miObject *obj = mi_api_object_begin(mi_mem_strdup (name) ) ; 
obj->visible = miTRUE; 

obj->shadow = 3; 
obj->bbox_min = bbox_min; 

obj->bbox_max = bbox_max; 
mi_api_object_file(mi_mem_strdup (filename) ) ; 


597 


598 


return mi_api_object_end() ; 


Chapter 20 — Modeling hair 


void miaux_define_hair_object( 
miTag name_tag, miaux_bbox_function bbox_function, void *params, 
miTag *geoshader_result, miApi_object_callback callback) 


{ 
miTag tag; 
mi0bject *obj; 
char *name = miaux_tag_to_string(name_tag, "::hair"); 
obj = mi_api_object_begin(mi_mem_strdup (name) ) ; 
obj->visible = miTRUE; 
obj->shadow = obj->reflection = obj->refraction = 3; 
bbox_function(obj, params) ; 
if (geoshader_result != NULL && callback != NULL) { 
mi_api_object_callback(callback, params) ; 
tag = mi_api_object_end() ; 
mi_geoshader_add_result (geoshader_result, tag); 
obj = (midbject *)mi_scene_edit (tag) ; 
obj->geo.placeholder_list.type = miQBJECT_HAIR; 
mi_scene_edit_end (tag) ; 
} 
} 
void miaux_describe_bbox(mi0bject *obj) 
{ 
mi_progress("Object bbox: 7f,%f,4f “Zf,4f,4f", 
obj->bbox_min.x, obj->bbox_min.y, obj->bbox_min.z, 
obj->bbox_max.x, obj->bbox_max.y, obj->bbox_max.z) ; 
} 


void miaux_adjust_bbox(miO0bject *obj, miVector *v, miScalar extra) 
{ 
miVector v_extra, vmin, vmax; 
miaux_set_vector(&v_extra, extra, extra, extra); 
mi_vector_sub(&vmin, v, &v_extra); 
mi_vector_add(&vmax, v, &v_extra); 
mi_vector_min(&obj->bbox_min, &obj->bbox_min, &vmin) ; 
mi_vector_max(&obj->bbox_max, &obj->bbox_max, &vmax) ; 


} 

void miaux_init_bbox(mi0bject *obj) 

{ 
obj->bbox_min.x = miHUGE_SCALAR; 
obj->bbox_min.y = miHUGE_SCALAR; 
obj->bbox_min.z = miHUGE_SCALAR; 
obj->bbox_max.x = -miHUGE_SCALAR; 
obj->bbox_max.y = -miHUGE_SCALAR; 
obj->bbox_max.z = -miHUGE_SCALAR; 

} 


void miaux_append_hair_vertex(miScalar **scalar_array, miVector *v) 


{ 


(*scalar_array) [0] = v->x; 
(*scalar_array) [1] = v->y; 
(*scalar_array) [2] = v->z; 


*scalar_array += 3; 


} 


void miaux_append_hair_data( 
miScalar **scalar_array, miVector *v, miScalar position, 
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miScalar root_radius, miColor *root, miScalar tip_radius, miColor *tip ) 


(*scalar_array) [0] 
(*scalar_array) [1] 


bel Ae 
V->y; 
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(*scalar_array) [2] = v->z; 
(*scalar_array) [3] = miaux_fit(position, 
(*scalar_array) [4] = miaux_fit(position, 
(*scalar_array) [5] = miaux_fit (position, 
(*scalar_array) [6] = miaux_fit (position, 
(*scalar_array) [7] = miaux_fit (position, 
*scalar_array += 8; 


1, root_radius, tip_radius) ; 
,» 1, Proot-or, tip-or): 
, ig Poct—-g, tip->g) ; 

af 

i 


3 


> 


, root->b, tip->b); 
, root->a, tip->a); 


OOOO 0 


> 


J 
double miaux_max(double a, double b) 
4 
returna>b?as:»b; 
} 
void miaux_copy_color(miColor *result, miColor *color) 
{ 
result->r = color->r; 
result->g = color->g; 
result->b = color->b; 
result->a = color->a; 
i 
void miaux_opacity_set_channels(miState *state, miScalar value) 
4, 
miColor opacity; 
miaux_set_channels(&opacity, value) ; 
mi_opacity_set(state, opacity) ; 
hy 


void miaux_add_transparent_hair_component(miColor *result, miState *state) 
{ 
miColor background_color; 
mi_trace_transparent (&background_color, state); 
if (result->a == 0) { 
miaux_opacity_set_channels(state, 0.0); 
miaux_copy_color(result, &background_color) ; 
} else { 
miaux_opacity_set_channels(state, result->a) ; 
miaux_blend_colors(result, result, &background_color, result->a) ; 


} 


void miaux_add_specular_hair_component ( 
miColor *result, miVector *hair_tangent, miVector *to_light, 
miVector *to_camera, 
miColor *specular, miColor *light_color) 


miScalar light_angle = acos(mi_vector_dot(hair_tangent, to_light)) ; 
miScalar view_angle = acos(mi_vector_dot(hair_tangent, to_camera) ) ; 
miScalar sum = light_angle + view_angle; 

miScalar specular_factor = fabs(M_PI_2 - fmod(sum, M_PI)) / M_PI_2; 


result->r += specular_factor * specular->r * light_color->r; 
result->g += specular_factor * specular->g * light_color->g; 
result->b += specular_factor * specular->b * light_color->b; 


} 


void miaux_add_diffuse_hair_component ( 
miColor *result, miVector *hair_tangent, miVector *to_light, 
miColor *diffuse, miColor *light_color) 


miScalar diffuse_factor = 1.0 - fabs(mi_vector_dot(hair_tangent, to_light)); 
miaux_add_diffuse_component (result, diffuse_factor, diffuse, light_color) ; 


} 


double miaux_clamp(double v, double minval, double maxval) 


! 


return v < minval ? minval : v > maxval ? maxval : v; 
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} 

void miaux_clamp_color(miColor *result) 

{ 
result->r = miaux_clamp(result->r, 0.0, 1.0); 
result->g = miaux_clamp(result->g, 0.0, 1.0); 
result->b = miaux_clamp(result->b, 0.0, 1.0); 
result->a = miaux_clamp(result->a, 0.0, 1.0); 

F 


void miaux_point_between ( 
miVector *result, miVector *u, miVector *v, float fraction) 


{ 
result->x = miaux_fit(fraction, 0, 1, u->x, v->x); 
result->y = miaux_fit(fraction, 0, 1, u->y, v->y); 
result->z = miaux_fit(fraction, 0, 1, u->z, v->z); 
} 


void miaux_perpendicular_point(miVector *result, miVector *v, float distance) 


{ 


result->x = -v->y; 
result->y = v->x; 
result->z = 0; 


mi_vector_normalize(result) ; 
mi_vector_mul(result, distance); 


} 


void miaux_hair_spiral ( 
miScalar** scalar_array, miVector *start_point, miVector *end_point, 
float turns, int point_count, float angle_offset, float spiral_radius, 
miScalar root_radius, miScalar tip_radius) 


{ 

miVector base_point, spiral_axis, spiral_point; 

miVector axis_point; 

miMatrix matrix; 

float angle, pi_2 = 2 * M_PI, max_index = point_count - 1; 

1nG 2% 

mi_vector_sub(&spiral_axis, end_point, start_point) ; 

mi_vector_normalize(&spiral_axis) ; 

miaux_perpendicular_point (&axis_point, &spiral_axis, spiral_radius) ; 

for (i = 0; i < point_count; i++) { 
float fraction = i / max_index; 
miaux_point_between(&base_point, start_point, end_point, fraction) ; 
angle = angle_offset + fraction * turns * pi_2; 
mi_matrix_rotate_axis(matrix, &spiral_axis, angle); 
mi_point_transform(&spiral_point, &axis_point, matrix); 
mi_vector_add(&spiral_point, &spiral_point, &base_point) ; 
*(*xscalar_array)++ = spiral_point.x; 
*(*xscalar_array)++ = spiral_point.y; 
*(*scalar_array)++ = spiral_point.z; 
*(*xscalar_array)++ = 

miaux_fit_clamp(i, 0, max_index, root_radius, tip_radius) ; 
} 
is 


void miaux_random_point_on_sphere( 
miVector *result, miVector *center, miScalar radius) 
{ 
miMatrix transform; 
result->x = radius; 
result->y = result->z = 0.0; 
mi_matrix_rotate(transform, 0, 
miaux_random_range(0, M_PI * 2), 
miaux_random_range(0, M_PI * 2)); 
mi_vector_transform(result, result, transform) ; 
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} 


mi_vector_add(result, result, center); 


void miaux_read_hair_data_file(char* filename, miScalar radius) 


{ 


} 


int vertex_count, total_vertex_count, hair_scalar_size, vertex_total = 0, 
index_array_size, v, *hair_indices, *hi, hair_count, per_hair_scalars; 

float xmin, ymin, zmin, xmax, ymax, zmax, age; 

miScalar coord, *hair_scalars; 

miGeoIndex *harray; 

FILE *fp; 


fp = fopen(filename, "r"); 
fscanf(fp, "%d 4d ", &hair_count, &total_vertex_count) ; 
faucanttip, ““AF wf “AF AT 4f ZF", 
&xmin, &ymin, &zmin, &xmax, &ymax, &zmax) ; 
mi_progress("particle bounding box: “%f %f “%f “fF “ff Zt ", 
xmin, ymin, zmin, xmax, ymax, zmax); 


per_hair_scalars = 2; 
mi_api_hair_info(0, ’r’, 1); 
mi_api_hair_info(0O, ’t’, 1); 


hair_scalar_size = hair_count * per_hair_scalars + total_vertex_count * 3; 
hair_scalars = mi_api_hair_scalars_begin(hair_scalar_size) ; 


index_array_size = 1 + hair_count; 

hi = hair_indices = (int*)mi_mem_allocate(sizeof(int) * index_array_size) ; 
*hit++ = 0; 

vertex_total = 0; 


while (!feof(fp)) { 
*hair_scalars++ = radius; 
fscanf(fp, "%f ", &age); 
*hair_scalarst++ = age; 
fscanf(fp, "4d ", &vertex_count) ; 
for (v = 0; v < vertex_count * 3; v++) { 
fscanf(fp, "%f ", &coord); 
*hair_scalarst++ = coord; 
} 
vertex_total += vertex_count * 3 + per_hair_scalars; 
*hit+t+ = vertex_total; 
} 
mi_api_hair_scalars_end(hair_scalar_size) ; 
harray = mi_api_hair_hairs_begin(index_array_size) ; 
memcpy (harray, hair_indices, index_array_size * sizeof(int)); 
mi_api_hair_hairs_end() ; 


void miaux_hair_data_file_bounding_box( 


} 


char* filename, 
float *xmin, float *ymin, float *zmin, 
float *xmax, float *ymax, float *zmax) 


int hair_count, data_count; 

FILE*x fp = fopen(filename, "r"); 

fscanf(fp, "Ad vd ", &hair_count, &data_count); /* Ignore. */ 
fscanf(fp, "Af “%Zf “ZF Af “Ff “ZF ", xmin, ymin, zmin, xmax, ymax, zmax); 
fclose(fp) ; 


void miaux_blend_transparency(miColor *result, 


{ 


miState *state, miColor *transparency) 


miColor opacity, background; 
miaux_invert_channels(&£opacity, transparency) ; 
mi_opacity_set(state, opacity) ; 

if (!miaux_all_channels_equal(transparency, 1.0)) { 
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mi_trace_transparent (&background, state) ; 
miaux_blend_channels(result, &background, &opacity) ; 


z 


void miaux_color_fit(miColor *result, 
miScalar f, miScalar start, miScalar end, 
miColor *start_color, miColor *end_color) 


{ 
result->r = miaux_fit(f, start, end, start_color->r, end_color->r) ; 
result->g = miaux_fit(f, start, end, start_color->g, end_color->g) ; 
result->b = miaux_fit(f, start, end, start_color->b, end_color->b) ; 
} 


Chapter 21 — The environment of the scene 


miScalar miaux_interpolated_lookup(miScalar lookup_table[], int table_size, 
miScalar t) 


{ 

int lower_index = (int) (t * (table_size - 1)); 

miScalar lower_value = lookup_table [lower_index] ; 

int upper_index = lower_index + 1; 

miScalar upper_value = lookup_table[upper_index] ; 

return miaux_fit( 

t * table_size, lower_index, upper_index, lower_value, upper_value) ; 

} 
float miaux_altitude(miState *state) 
{ 

miVector ray; 

mi_vector_to_world(state, kray, &state->dir) ; 

mi_vector_normalize(&ray) ; 

return miaux_fit(asin(ray.y), -M_PI_2, M_PI_2, 0.0, 1.0); 
i 


void miaux_piecewise_sinusoid( 
miScalar result[], int result_count, 
int key_count, miScalar key_positions[], miScalar key_values[]) 


{ 
int key, 1; 
for (key = 1; key < key_count; key++) { 
int start = (int) (key_positions[key-1] * result_count) ; 
int end = (int) (key_positions[key] * result_count) - 1; 
for (i = start; i <= end; i++) { 
result[i] = miaux_sinusoid_fit( 
i, start, end, key_values[key-1], key_values[key]); 
i 
: 
} 


miBoolean miaux_release_user_memory(char* shader_name, miState *state, void *params) 
{ 
if (params != NULL) { /* Shader instance exit */ 
void **user_pointer; 
if (!mi_query(miQ_FUNC_USERPTR, state, 0, &user_pointer)) 
mi_fatal("Could not get user pointer in shader exit function %s_exit", 
shader_name) ; 
mi_mem_release(*user_pointer) ; 
} 
return miTRUE; 


} 


void* miaux_user_memory_pointer(miState *state, int allocation_size) 
{ 

void **user_pointer; 

mi_query(miQ_FUNC_USERPTR, state, 0, &user_pointer) ; 

if (allocation_size > 0) { 
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*xuser_pointer = mi_mem_allocate(allocation_size) ; 


return *user_pointer; 


} 


void miaux_interpolated_color_lookup(miColor* result, 
miColor lookup_table[], int table_size, 
miScalar t) 


{ 
int lower_index = (int)(t * table_size) ; 
miColor lower_value = lookup_table[lower_index] ; 
int upper_index = lower_index + 1; 
miColor upper_value = lookup_table[upper_index] ; 
result->r = miaux_fit(t * table_size, lower_index, upper_index, 
lower_value.r, upper_value.r) ; 
result->g = miaux_fit(t * table_size, lower_index, upper_index, 
lower_value.g, upper_value.g) ; 
result->b = miaux_fit(t * table_size, lower_index, upper_index, 
lower_value.b, upper_value.b) ; 
} 


void miaux_piecewise_color_sinusoid( 
miColor result[], int result_count, int key_count, miColor key_values[]) 


1, 
int key, i; 
for (key = 1; key < key_count; keyt++) { 
int start = (int) (key_values[key-1].a * result_count) ; 
int end = (int) (key_values[key].a * result_count) - 1; 
for (i = start; i <= end; i++) { 
result [i].r = 
miaux_sinusoid_fit( 
i, start, end, key_values[key-1].r, key_values[key].r); 
result [i].g = 
miaux_sinusoid_fit ( 
i, start, end, key_values[key-1].g, key_values [key] .g); 
result[i].b = 
miaux_sinusoid_fit ( 
i, start, end, key_values[key-1].b, key_values[key] .b); 
} 
} 
} 


Chapter 22 — A visible atmosphere 


void miaux_point_along_vector ( 
miVector *result, miVector *point, miVector *direction, miScalar distance) 


{ 
result->x = point->x + distance * direction->x; 
result->y = point->y + distance * direction->y; 
result->z = point->z + distance * direction->z; 
} 


void miaux_march_point ( 
miVector *result, miState *state, miScalar distance) 


{ 


miaux_point_along_vector(result, &state->org, &state->dir, distance) ; 


void miaux_world_space_march_point ( 
miVector *result, miState *state, miScalar distance) 
{ 
miaux_march_point(result, state, distance) ; 
mi_vector_to_world(state, result, result); 
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Chapter 23 — Volumetric effects 


miScalar miaux_threshold_density ( 
miVector *point, miVector *center, miScalar radius, 
miScalar unit_density, miScalar march_increment) 


{ 
miScalar distance = mi_vector_dist(center, point) ; 
if (distance <= radius) 
return unit_density * march_increment ; 
else 
return 0.0; 
Fr 


miScalar miaux_density_falloff ( 
miVector *point, miVector *center, miScalar radius, 
miScalar unit_density, miScalar march_increment) 


return march_increment * unit_density * 
miaux_fit_clamp(mi_vector_dist(center, point), 0.0, radius, 1.0, 0.0); 


} 


void miaux_alpha_blend_colors ( 
miColor *result, miColor *foreground, miColor *background) 


| 
double bg_fraction = 1.0 - foreground->a; 
result->r = foreground->r + background->r * bg_fraction; 
result->g = foreground->g + background->g * bg_fraction; 
result->b = foreground->b + background->b * bg_fraction; 
} 


void miaux_add_transparent_color( 
miColor *result, miColor *color, miScalar transparency) 


| 
miScalar new_alpha = result->a + transparency; 
if (new_alpha > 1.0) 

transparency = 1.0 - result->a; 

result->r += color->r * transparency; 
result->g += color->g * transparency; 
result->b += color->b * transparency; 
result->a += transparency; 

t 


void miaux_total_light_at_point ( 
miColor *result, miVector *point, miState *state, 
miTag* light, int light_count) 


{ 
miColor sum, light_color; 
int i, light_sample_count; 
miVector original_point = state->point; 
state->point = *point; 
miaux_set_channels(result, 0.0); 
for (i = 0; i < light_count; i++, light++) f{ 
miVector direction_to_light; 
light_sample_count = 0; 
miaux_set_channels(&sum, 0.0); 
while (mi_sample_light(&light_color, &direction_to_light, NULL, 
state, *light, &light_sample_count) ) 
miaux_add_scaled_color(&sum, &light_color, 1.0); 
if (light_sample_count) 
miaux_add_scaled_color(result, &sum, 1/light_sample_count) ; 
} 
state->point = original_point; 
} 


miScalar miaux_fractional_occlusion_at_point ( 
miVector *start_point, miVector *direction, 
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} 


miScalar total_distance, miVector *center, miScalar radius, 
miScalar unit_density, miScalar march_increment) 


miScalar distance, occlusion = 0.0; 
miVector march_point; 
mi_vector_normalize(direction) ; 
for (distance = 0; distance <= total_distance; distance += march_increment) { 
miaux_point_along_vector(&march_point, start_point, direction, distance) ; 
occlusion += miaux_threshold_density(&march_point, center, radius, 
unit_density, march_increment) ; 
if (occlusion >= 1.0) { 
occlusion = 1.0; 
break; 
} 
} 


return occlusion; 


miScalar miaux_fractional_shader_occlusion_at_point ( 


} 


miState *state, miVector *start_point, miVector *direction, 
miScalar total_distance, miTag density_shader, 
miScalar unit_density, miScalar march_increment) 


miScalar density, distance, occlusion = 0.0; 
miVector march_point; 
miVector original_point = state->point; 
mi_vector_normalize (direction) ; 
for (distance = 0; distance <= total_distance; distance += march_increment) { 
miaux_point_along_vector(&march_point, start_point, direction, distance) ; 
state->point = march_point; 
mi_call_shader_x((miColor*)&density, miSHADER_MATERIAL, state, 
density_shader, NULL) ; 
occlusion += density * unit_density * march_increment ; 
if (occlusion >= 1.0) { 
occlusion = 1.0; 
break; 
} 
} 
state->point = original_point; 
return occlusion; 


miBoolean miaux_point_inside(miVector *p, miVector *min_p, miVector *max_p) 


i 


} 


return p->x >= min_p->x && p->y >= min_p->y && p->z >= min_p->z && 
p->x <= max_p->x && p->y <= max_p->y && p->z <= max_p->z; 


void miaux_read_volume_block( 


char* filename, 
int *width, int *height, int *depth, float* block) 


10% count: 
FILE* fp = fopen(filename, "r"); 
if (fp == NULL) { 
mi_fatal("Error opening file \"%s\".", filename) ; 
} 
fscanf(fp, "%d %d id ", width, height, depth) ; 
count = (*width) * (*height) * (*depth) ; 
mi_progress("Volume dataset: %dx/dx/d", *width, *height, *depth) ; 
fread(block, sizeof(float), count, fp); 


Chapter 24 — Changing the lens 


double miaux_distance(double x1, double y1, double x2, double y2) 
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double x = x2 - x1, y = y2 - y1; 
return sqrt(x * x + y * y); 


} 


void miaux_divide_color(miColor *result, miColor* color, miScalar f) 
A 

color->r / f; 

color—>g,/> ft: 

color->b / f; 


result->r 
result-—>g 
result->b 


} 


void miaux_from_camera_space( 
miState *state, miVector *origin, miVector *direction) 
mi_point_from_camera(state, origin, origin) ; 
mi_vector_from_camera(state, direction, direction) ; 


} 


void miaux_square_to_circle( 
float *result_x, float *result_y, float x, float y, float max_radius) 


{ 
float angle = M_PI * 2 * x; 
float radius = max_radius * sqrt(y); 
*result_x = radius * cos(angle) ; 
*result_y = radius * sin(angle) ; 

} 


void miaux_sample_point_within_radius( 
miVector *result, miVector *center, float x, float y, float max_radius) 


{ 
float x_offset, y_offset; 
miaux_square_to_circle(&x_offset, &y_offset, x, y, max_radius) ; 
result->x = center->x + x_offset; 
result->y = center->y + y_offset; 
result->z = center->z; 
} 


void miaux_z_plane_intersect ( 
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miVector *result, miVector *origin, miVector *direction, miScalar z_plane) 


{ 
miScalar z_delta = (z_plane - origin->z) / direction->z; 
result->x = origin->x + z_delta * direction->x; 
result->y = origin->y + z_delta * direction->y; 
result->z = z_plane; 

t 


void miaux_to_camera_space( 
miState *state, miVector *origin, miVector *direction) 
{ 
mi_point_to_camera(state, origin, &state->org) ; 
mi_vector_to_camera(state, direction, &state->dir); 


Chapter 25 — Rendering image components 


void miaux_divide_colors(miColor *result, miColor *x, miColor *y) 


{ 


result->r = y->r == 0.0 71.0: x->r / y->r; 
result->g = y->g == 0.0 7? 0.0 : x->g / y->g; 
result->b = y->b == 0.0 7 1.0 : x->b / y->b; 


} 


void miaux_add_light_color( 

miColor *result, miState *state, miTag light, char shadow_state) 
{ 

int light_sample_count = 0; 
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miScalar dot_nl; 
miVector direction_toward_light ; 
miColor sample_color, single_light_color; 


const mi0ptions *original_options = state->options; 
miOptions options_copy = *original_options; 
options_copy.shadow = shadow_state; 

state->options = koptions_copy; 


miaux_set_channels(&single_light_color, 0.0); 
while (mi_sample_light(&sample_color, &direction_toward_light, 
&dot_nl, state, light, &light_sample_count) ) 


miaux_add_scaled_color(&single_light_color, &sample_color, dot_nl); 


if (light_sample_count) 
miaux_add_scaled_color(result, &single_light_color, 
1.0/light_sample_count) ; 


state->options = (mi0ptions*)original_options; 


Chapter 26 — Modifying the final image 


int miaux_color_compare(const void *vx, const void *vy) 


{ 

miColor const *x = vx, *y = vy; 

float sum_x = x->r + x->g + x->b; 

float sum_y = y->r + y->g + y->b; 

return sum_x < sum_y ? -1 : sum_x > sum_y 7? 1: QO; 
} 


void miaux_pixel_neighborhood ( 
miColor *neighbors, 
milmg_image *buffer, int x, int y, int radius) 


{ 
int xi, yi, xp = 0, yp=0, i= 0, 
max_x = buffer->width - 1, max_y = buffer->height - 1; 
miColor current_pixel; 
for (yi = y - radius; yi <= y + radius; yit++) { 
yp = yi > max_y ? max_x : yi < 070: yi; 
for (xi = x - radius; xi <= x + radius; xit+) { 
xp = xi > max_x 7? max_x : xi < 070: xi; 
mi_img_get_color(buffer, &current_pixel, xp, yp); 
neighbors[i++] = current_pixel; 
} 
} 
t 
void miaux_release_fontimage(fontimage *fimage) 
{ 
mi_mem_release(fimage->x_offsets) ; 
mi_mem_release(fimage->image) ; 
F 


void miaux_alpha_blend(miColor *x, miColor *y, miScalar alpha) 
{ 

x->r = miaux_blend(y->r, x->r, alpha); 

x->g = miaux_blend(y->g, x->g, alpha); 

x->b = miaux_blend(y->b, x->b, alpha); 


} 


void miaux_text_image ( 
float **text_image, int *width, int *height, 
fontimage *fimage, char* text) 


char *c; 
int i, total_width, xpos, first_printable = 32, image_size, 
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index, start, end, font_index, fx, fy, tx, ty, text_index; 


for (i = 0, total_width = 0, c = text; i < strlen(text); i++, c++) { 
index = *c - first_printable; 
start = fimage->x_offsets [index] ; 
end = fimage->x_offsets[index + 1]; 
total_width += end - start + 1; 
i 
*width = total_width; 
*height = fimage->height ; 
image_size = *width * *height; 
(*text_image) = (float*)mi_mem_allocate(image_size * sizeof (float)) ; 


for (i = 0, c = text, xpos = 0; i < strlen(text); i++, c++) { 
int index *c — first_printable; 
start = fimage->x_offsets [index] ; 
end = fimage->x_offsets[index + 1]; 
for (fy = fimage->height - 1, ty = 0; fy >= 0; fy--, tyt++) { 
for (fx = start, tx = xpos; fx < end-1; fx++, tx++) { 
text_index = ty * *width + tx; 
font_index = fy * fimage->width + fx; 
(*text_image) [text_index] = 
(float)fimage->image[font_index] / 255.0; 


xpos += end - start + 1; 


} 


void miaux_load_fontimage(fontimage *fimage, char* filename) 
{ 

int printable_ascii_size = 126 - 32 + 1; 

int i, image_data_size; 

char identifier [33]; 


FILE*x fp = fopen(filename, "r"); 
if (fp == NULL) 
mi_fatal("Could not open font image file: %s", filename) ; 
fscanf(fp, "4s ", identifier); 
if (strcmp(identifier, "FONTIMAGE") != 0) 
mi_fatal("File ’%s’ does not look like a fontimage file", filename) ; 


fscanf(fp, "Ad %d ", &fimage->width, &fimage->height) ; 
image_data_size = fimage->width * fimage->height; 
fimage->x_offsets = 

(int*)mi_mem_allocate(sizeof (int) * printable_ascii_size) ; 
for (i = 0; i <= printable_ascii_size; i++) 

fscanf(fp, "%d ", &fimage->x_offsets[i]); 
fimage->image = (unsigned char*)mi_mem_allocate(image_data_size) ; 
fread(fimage->image, image_data_size, 1, fp); 


fclose(fp); 


Appendix C 


Creating fontimage files 


The “fontimage” file format in Chapter 26 consists of descriptive information in ASCII followed 
by grayscale image data in binary format. The file begins with the identifying string FONTIMAGE, 
followed by the width and height of the grayscale image. A list of horizontal offsets then define 
the position of the printable ASCII characters in the grayscale image. This is followed by the 
binary image data. 


Identification string 


Width and height of font image image width image height 
Horizontal offset for each character x1 be xn 


Image data, one byte per pixel, row major order binary image data 


Figure C.1: Data format of “fontimage” file 


To create a grayscale image of a font, I construct a PostScript file that displays the printable ASCII 
characters (from 26 to 132). 


Figure C.2: Part of the fontimage for 24 point Helvetica 


This PostScript file is then converted to a grayscale image with the Ghostscript and ImageMagick 
packages which can be downloaded from the Web. 


Ghostscript http://www.cs.wisc.edu/~ghost/ 
ImageMagick http://www.imagemagick.org/script/index.php 


The following Python script (and the PostScript file it processes) creates a fontimage file. Error 
checking is minimal. In particular, the ImageMagick and Ghostscript packages are assumed to 
exist in the executable path of the shell invoked by the Python os.system function. The full 
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pathname can be specified instead by modifying the values of the GHOSTSCRIPT and CONVERT 
variables in the fontimage.py Python script. 


Once the fontimage file has been constructed, the “annotate” output shader (on page 447) only 
needs the fontimage file to add text to an image at the end of rendering. Ghostscript and 
ImageMagick are not required when the “annotate” shader is run. This means that fontimage 
files can be constructed on a system with Ghostscript and ImageMagick installed, and then 
distributed to systems rendering scenes using “annotate.” 


C.1 Python script fontimage.py 


Python script fontimage. py constructs a fontimage based on the font’s name and size provided 
as arguments. These arguments are then passed to a PostScript file, fontimage_components. ps, 
which is then processed by Ghostscript. The component files for the fontimage are generated by 
fontimage_components.ps. The PostScript file that describes the character image is rasterized 
by the ImageMagick convert program. Script fontimage. py then joins the header and body files 
into the single fontimage file. 


#!/usr/bin/python 
import sys, re, os 


if len(sys.argv) not in [3,4]: 
print **? 
Usage: fontimage.py [-v] <fontname> <fontsize> 


Create a "fontimage" file to use with the "annotate" shader as 
described in Chapter 26 of "Writing mental ray shaders". This script 
uses the file "fontimage_components.ps" to generate the header and 
image data of the fontimage file. 


If the optional "-v" (verbose) flag is present, the processing steps 
that create the fontimage file from the fontimage_components.ps file 
are listed, and and image of the characters is also created that can 
be displayed with any image viewer. 


For example, to create a fontimage of Helvetica-BoldOblique at size 32 
points, enter: 


fontimage.py HelveticaBold-Oblique 32 


For a description of how the fontimage is constructed, use the "-v" 
flag: 


fontimage.py -v HelveticaBold-Obligue 32 


223 


sys.exit(1) 


'This is, of course, an example of a heterogeneous programming style that is so often useful in commercial production 
but would be considered questionable in more theoretical contexts. 


# Ghostscript "gs" command (change to reflect actual pathname): 
GHOSTSCRIPT = ’gs’ 


# ImageMagick "convert" command (change to reflect actual pathname): 
CONVERT = ’convert’ 


def system(s, verbose): 
if verbose: 
print s 
if os.system(s): 
print ’Error executing "/s"’ % (s) 
sys.exit (1) 


# Process script arguments: 
args = sys.argv[1:] 
verbose = False 
it "=v" in arge: 
verbose = True 
args.remove(’-v’) 
fontname, fontsize = args 


# Construct filenames: 

basename = ’%4s_%s’ % (fontname, fontsize) 
header_filename = ’%s.header’ % (basename) 
body_filename = ’%s.body’ % (basename) 
imagedata_filename = ’%s.raw’ % (basename) 
fontimage_filename = ’4s.fontimage’ % (basename) 


if verbose: 
print ’\nConstruction of a fontimage for %s, 4s point:\n’ % \ 
(fontname, fontsize) 


# Run the PostScript file to generate the fontimage components: 
system(’%s -q -dNODISPLAY -- fontimage_source.ps %s fs’ h \ 
(GHOSTSCRIPT, fontname, fontsize), verbose) 


# Convert the PostScript definition of the characters to a raster image: 
system(’%s -quality 100 %s gray:%s’ % \ 
(CONVERT, body_filename, imagedata_filename), verbose) 


# Combine the header file and raster image data into the fontimage: 

fp = open(fontimage_filename, ’w’) 

fp.write(open(header_filename).read() + open(imagedata_filename) .read()) 
fp.close() 


# Create a separately displayable image of the font if in verbose mode: 
if verbose: 
character_image_filename = ’%s.tif’ % (basename) 
system(’convert -quality 100 z%s hs’ % \ 
(body_filename, character_image_filename), verbose) 


print ’\nFontimage file %s constructed.’ % (fontimage_filename) 
if verbose: 
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print ’\nTo see the characters in the font, enter the following:’ 

print *\n display %s’ % (character_image_filename) 

print ’\nThis file is for reference only and can be deleted.’ 
else: 

os. remove (header_filename) 

os .remove (body_filename) 

os. remove (imagedata_filename) 
print 


C.2 PostScript file fontimage components.ps 


The following PostScript file is used by Python script fontimage.py (described above) to generate the 
fontimage header file and the PostScript file that will generate the image data. 


h! 

/ Fontimage construction using this PostScript file to create 

/ Character position and image data for the fontimage file. 

/ When Ghostscript is invoked, the font’s name and size are passed 
/ into the ARGUMENTS array, like so: 

/ gs -dNODISPLAY -- fontmetrics.ps Courier 12 


/ Get fontname and fontsize arguments and set the font: 


/fontname ARGUMENTS O get def 
/fontsize ARGUMENTS 1 get cvi def 
fontname findfont fontsize scalefont setfont 


% Utilities: 
/edef { exch def } bind def 


/concat { 
exch dup length 
2 index length add string 
dup dup 4 2 roll copy length 
4 -1 roll putinterval 

} bind def 


/putstring { outfile exch writestring } bind def 

/putspace { outfile ( ) writestring } bind def 

/putnewline { outfile (\n) writestring } bind def 
/putnumber { buffer cvs outfile exch writestring } bind def 


/output_char { 
12 dict begin 
/c exch def 
c (\Q eq c (\)) eq or c (\\) eq or 
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{ (\(\\) putstring } 
{ (\Q putstring } 
ifelse 
c putstring (\)) putstring 
end 
} bind def 


/drawline { % For debugging. 
xpos putnumber ( 0 moveto ) putstring 
xpos putnumber putspace font_height putnumber 
( lineto stroke\n) putstring 

} bind def 


% Filename construction: 


/buffer 64 string def 

/basename fontname buffer cvs (_) concat fontsize buffer cvs concat (.) concat def 
/header_filename basename (header) concat def 

/body_filename basename (body) concat def 


% Character array for the font. The first array position defines the 
% width of the space character in terms of another characer (in this 
% case, "n", to mimic an "en-space"). 


/characters 

(n! "#$7&? () *+,-./0123456789: ;<=>70\ 
ABCDEFGHI JKLMNOPQRSTUVWXYZ\ 

[\\] *_‘abcdefghijklmnopqrstuvwxyz{|}~) 
def 


/character_count characters length def 


% Calculate the character widths and relative offset of each 
% character, storing in array char_x_positions and char_x_offsets: 


/font_ymin fontsize 2 mul def 

/font_ymax fontsize neg def 

/char_x_positions character_count array def 
/char_x_offsets character_count array def 
/left_margin 1 def 

/right_margin 1 def 

/width_increase left_margin right_margin add def 
/last_xpos 0 def 

/xpos 0 def 


O 1 character_count 1 sub { 
/i edef 
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char_x_positions i xpos put 


characters i 1 getinterval 
newpath 0 O moveto false charpath closepath pathbbox 
/ymax edef /xmax edef /ymin edef /xmin edef 


/font_ymin font_ymin ymin min def 
/font_ymax font_ymax ymax max def 


/xpos xmax xmin sub ceiling xpos add width_increase add cvi def 
char_x_offsets i xmin ceiling cvi left_margin sub put 
} for 


/full_font_width xpos cvi def 

/font_ymin font_ymin floor def 

/font_ymax font_ymax ceiling def 
/font_height font_ymax font_ymin sub cvi def 


/ Write the fontimage header to file: 


/outfile header_filename (w) file def 
(FONTIMAGE\n) putstring 

full_font_width putnumber putspace 

font_height putnumber putnewline 

0 1 character_count 1 sub 

{ char_x_positions exch get putnumber putspace } 
for 

putnewline 

outfile closefile 


/, Write the PostScript file that will created the image data when 
/, rasterized with the ImageMagick convert command: 


characters 0 32 put % Replace the space character placeholder 


/outfile body_filename (w) file def 

(4!\n4ZBoundingBox: O 0 ) putstring 

full_font_width putnumber putspace font_height putnumber putnewline 

(O setgray 0 0 ) putstring full_font_width putnumber putspace font_height putnumber 
( rectfill 1 setgray ) putstring putnewline 


(/) putstring 
fontname putnumber 
( findfont ) putstring fontsize putnumber ( scalefont setfont\n) putstring 
(1 setlinewidth\n) putstring 
/ypos font_ymin neg cvi def 
O 1 character_count 1 sub 
{ 
/i exch def 


/char characters i 1 getinterval def 
/xpos char_x_positions i get def 
/xoff char_x_offsets i get def 
% drawline % Uncomment to check character spacing. 
xpos xoff sub putnumber putspace ypos putnumber ( moveto ) putstring 
char output_char ( show\n) putstring 
} for 
(showpage\n) putstring 
outfile closefile 


% Files <fontname>_<fontsize>.header and <fontname>_<fontsize>.body 
% are now ready to be processed and combined by script fontimage.py. 
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210 
mi_vector_add, 264, 267 
mi_vector_dist, 252, 264, 383, 388 
mi_vector_dot, 61,99, 115 
mi_vector_from_camera, 411 
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mi_vector_sub, 417 
mi_vector_to_camera, 411 
mi_vector_to_object, 62, 264, 267 
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application programming interface, 52 
approximation 
statement, 107 
view dependent, 107 
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architecture, 1, 3 
area light 
command, 143 
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disc, 145 
object, 145 
primitives, 145 
rectangle, 145 
sample loop, 154 
sampling, 145 
sphere, 145 
user, 145 
argument evaluation, 71 
arithmetic operators, 212 
array of integers, 193 
array parameter, 194 
syntax, 152 
type, 53 
aspect ratio, 399, 441 
autovolume mode, 171 
auxiliary functions, 66 
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background color, 71 
barycentric coordinates, 109, 292 
base shaders, 28 
base.mi, 28 

blending weight, 212 
Blinn, James, 156 
Boolean parameters, 78 
bounding box, 280 
brevity and clarity, 55 
Bui-Tuong, Phong, 154 
bump basis vectors, 263 
bump mapping, 32 
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callback function, 282, 289 
camera 
angle of view, 399 
aperture, 399 


circle of confusion, 412 

coordinate space, 408 

depth of field, 412 

equirectangular projection, 404 

eye rays, 400 

focal length, 399 

instance, 15 

metaphor, 11 

physical lens, 412 

pinhole model, 399 

projection space, 412 

resolution, 399 

scene file block, 399 

space, 407 

viewing plane, 399 

wide-angle lens, 408 
caustics, 219, 232 
chain of parent states, 201 
checking the ray type, 180 
circle of confusion, 412 
clarity and brevity, 55 
cleanup, 339 
color 

alpha, 25 

comparisons, 73 

components, 25 

data type, 25 

parameters, 27 

ramp, 333, 340, 342, 405 
color blending, 65 
color ramp, 333, 340, 342, 405 
comment character (#), 29 
compositing text, 447 
conditionals, 70 
connecting shaders, 37 
contour rendering, 93 
contours 

compositing contour output, 104 

contrast shader, 98, 100 

four shader types, 93 

grouping shaders, 106 

output shader, 102 

PostScript output, 104 

scene file shader locations, 95 

store shader, 96 
contract of a shader, 127 
Cook, R.L., 158 
coordinate space functions, 263 
cosine as projection, 133 
creating test scenes, 171 
critical angle, 197, 199 
C++ shaders, 452 
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Direr, Albrecht, 2 

database of the scene, 14 
access, 134 

deferred shader evaluation, 71 

definition before reference, 15 

density, 360, 370 
accumulation, 371 
function, 371 

depth fading, 63 

depth of field, 412 

design first, debug later, 68 

diffuse reflector, 149 

direct illumination, 219 

displacement shader, 247 

dot product visualization, 132 

drawing edges, 93 

Driemeyer, Thomas, 6 


E 
Emacs, modeling in, 13, 89 
encapsulation, 42 

material, 44 

shader, 44 
equirectangular projection, 404 
exit shader function, 342 
exponential explosion, 192 
exporting a scene file, 20 
expressive efficiency, 74 
eye rays, 400 
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fake specular highlights, 162 
falloff distance, 242 
field of view, 399 
final gathering, 220, 230 
rays, 231 
saved to file, 220 
trace depth, 231 
fisheye lens, 408 
floating point accuracy, 440 
focus plane, 414 
fontimage file format, 447 
as character lookup table, 448 
frame buffers, 421 
illumination components, 426 
index, 422 
standard, 421 
types, 439 
user, 422, 445 
functional modularity, 67 
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G 
geometric hair primitive, 289 
geometry shader API, 271 


global illumination, 44, 46, 151, 219 


accuracy, 220 

radius, 220 
global scope, 436 
glossy refraction, 206 
grammatical overtones, 19 
grazing angle, 213 
group block, 13 


H 
hair 
approximation, 300 
Beziér curve, 291 
data arrays, 290 
degree, 299 
geometric primitive, 271 
index array, 290 
linear curve, 291 
list structure, 299 
per-vertex data, 303 
quadric curve, 291 
radius, 290 
scalar array, 290 
tangent vector, 316 
vertices, 290 
hierarchies, 16 
HTML version of Volume II, 60 
hull, 370 
Humphrey, Greg, 5 


illumination shader structure, 160 
image processing, 439 
border conditions, 444 
four basic actions, 439 
get and put operations, 442 
integer coordinates, 439 
pseudocode, 440 
incident light, 223 
incident ray, 183 
$include command, 16 
incremental changes, 283 
indentation, 13 
index of refraction, 197 
diamond, 197 
glass, 197 
indirect illumination, 219 
init shader function, 342 
initialization, 339 
instance, 14 


group, 286 

groups, 16 

light, 134, 137, 145, 147 

light interaction, 128 

multiple, 286 

root group, 17 

scene file block, 286 
intensity falloff, 146 
internal space, 263 
inter-object reflections, 184 
interpolating colors, 64 
isotropic, 160 


K 
Kandinsky, Wassily, 3 
Knuth, Donald, 5 


L 
Lambert, Johann Heinrich, 149 
Lambert’s cosine law, 149 
lens, 399 
aperture, 412 
pinhole, 399 
shader, 399 
levels of detail, 253 
light 
area light sampling, 145 
array, 151 
direction, 132 
element, 127 
list, 33 
loop in shader, 152, 153 
origin, 128 
parameter access by query, 134 
parameters, 128 
point, 127 
shader contract, 127 
shader’s role in the scene, 128 
shadows cast by, 130 
spotlight geometry, 132 
spread, 132 
link command, 16 
literate programming, 5 
local illumination, 150, 219 
local lighting environment, 220 
lookup table, 342 
L-value, 55 


M 

manufacturing shapes, 14 
mapping, 77 

marble, 92 

marginal notes, 6 


material, 13, 29 
material Phenomena, 44 
declaration, 45 
frame buffer creation, 434 
photon shaders, 434 
root material, 45 
material shaders, 30 
mathematical utilities, 61 
median filter, 443 
mental ray standalone, 19 
metaphor, 11 
miaux functions, see utility functions 
miColor, 25 
microfacets, 156 
milmg_image, 439 
mi_query, 106 
mirror direction, 183 
mi_sample loop, 191 
.mi scene description language, 11 
modeling application, 13 
monolithic design approach, 212 
Morley, R. Keith, 5 
multiply two colors, 25 


N 

named shader, 29, 30, 224 
namespace, 276 
non-photorealistic effects, 93 


O 
object flags, 276 
occluding objects, 167 
occlusion factor, 379 
opacity, 58, 74 
optimization, 68 
optional shaders, 29 
options, 12, 226 
orientation, 58 
output 
handling shader interrupts, 442 
multiple shaders, 451 
shader order, 452 
shaders, 439 
statements, 421, 439 
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parameter array, 151 
parsing, 14 

particle systems, 326 
parts of speech, 19 
Perlin noise, 89 
perturbing normals, 259 
Pharr, Matt, 5 
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Phenomena, 41 
adding shader outputs, 430 
blending, 212 
component design, 212 
components, 42 
exploratory development, 433 
frame buffer components, 430 
interface parameters, 42, 43 
name, 43 
primary root shader statement, 43 
result type, 43 
root shader, 43 
shader definitions, 43 
shader visualization, 217 
Phong, Bui-Tuong, see Bui-Tuong, 
Phong 
photography, 11 
photon map, 45, 219 
photons, 220 
photon shader, 45, 220 
photo-realism, 2 
pinhole camera, 399 
pixel access functions, 440 
pixel neighborhood, 443 
sorting, 444 
placeholder objects, 271, 282 
predefined words, 12 
premultiplied RGB, 381 
primitive, hair, 289 
primitives, 106 
area light, 145 
boundary drawing, 106 
contour sampling, 109 
disabling normal vector check, 383 
index of, 106 
procedural geometric definition, 277 
projection, 404 
camera, 412 
equirectangular, 404 
pinhole, 399 
point, 411 
texture, 86 
pseudo-random numbers, 281 
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quantized uv coordinates, 80 
quasi-Monte Carlo integration, 190 
query request codes, 106, 134 
quotation marks, 12 


R 
random seed, 281 
rasterizer, 71, 308, 319 
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opacity, 71 
ray marching, 360 

increment, 361 

loop, 363 

march points, 361, 370 
recursive shader call, 70 
redundant parameter evaluation, 71 
refraction, 197 

glossy, 206 

homogeneous assumption, 198 

limiting sampling, 207 

using mi_sample, 208 
registering a callback, 289 
rendering, 1 

options that control, 12 
rendering state, 23, 28, 32, 50, 57, 61, 93, 

96 

C structure, 57 
representational painting styles, 3 
rescaling, 66 
reserved word, 12 
resolution, 399 
RGBA frame buffer, 423 
root material, 45 
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Saarinen, Eliel, 1 

scene 
commands, 16 
components, 11 
database, 14, 16, 29, 53, 102, 103, 106, 134, 

135, 137, 241, 271, 274, 276, 277,281, 
295, 289, 295, 298, J0D 

database editing, 295 
elements, 11 
file, 11 
grammar, 273 
statements, 12 

scientific accuracy, 4 

shader, 11 
as analysis tool, 61 
arbitrary input, 22 
assignment, 256 
basic structure, 24 
common structure, 50 
contract, 167 
declaration, 17, 26, 28 
default keyword, 27 
default parameter values, 27 
definition, 26, 29 


environment, 60, 184-186, 188, 339, 340, 343, 
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geometry, 271 


good parameter defaults, 91, 148 

graph, 37, 71 

graphs, 4 

instance, 346 

lens, 28 

list, 23, 24, 30, 252, 260 

missing parameters, 27 

name, 50 

option requirements, 401 

options, 28 

parameter list, 26 

parameters, 13, 23, 25, 50, 51 

passing parameters, 59 

Phenomena, 44 

result, 24 

result argument, 50 

return type, 50 

simplest, 49 

standard structure, 21 

state argument, 50, 57 

structure, 21 

type identifier, 29 

typical model, 24 

typical structure, 24 

use of previous result, 24 

user pointer, 347 

variable inputs, 22 

version, 28 

volume, 357, 369 

shader source code 

add_colors, 431, 580 

ambient_occlusion, 240, 526 

ambient_occlusion_cutoff, 242, 
527 

annotate, 450, 583 

average_radiance, 225, 523 

average_radiance_options, 229, 
524 

blinn, 158, 502 

bump_ripple, 264, 532 

bump_texture, 267, 534 

bump_wave, 261, 531 

bump_wave_uv, 262, 532 

c_contour, 101, 488 

c_contrast, 99, 487 

c_output, 102, 488 

c_store, 97, 487 

c_tessellate, 107, 490 

c_toon, 115, 493 

channel_ramp, 347-349, 558 

chrome_ramp, 343, 344, 557 

color_ramp, 352, 353, 560 

cook_torrance, 159, 503 
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default_lens, 402, 573 
density_volume, 376, 566 
depth_fade, 63, 478 
depth_fade_tint, 65, 478 
depth_fade_tint_2, 67, 479 
depth_fade_tint_3, 67, 480 
depth_of_field, 417, 576 
displace_ripple, 252, 529 
displace_texture, 254, 530 
displace_wave, 249, 528 
displace_wave_uv, 251, 528 
equirectangular, 405, 574 
fisheye, 411,575 
fog, 359, 561 
framebuffer_put, 430, 580 
front_bright, 58, 476 
front_bright_dot, 61, 477 
front_bright_steps, 114, 492 
global_lambert, 221, 522 
glossy_reflection, 187,513 
glossy_reflection_sample, 190, 
514 
glossy_reflection_sample_varying, 193, 
514 
glossy_refraction, 206, 517 
glossy_refraction_sample, 208, 
518 
glossy_refraction_sample_varying, 210, 
519 
ground_fog, 363, 562 
ground_fog layers, 365, 563 
hair_color_bary, 298, 541 
hair_color_fire, 333, 556 
hair_color_light, 315, 316, 318, 549 
hair_color_texture, 308, 546 
hair_geo_2v, 294-296, 540 
hair_geo_4v, 300, 301, 542 
hair_geo_4v_texture, 305-307, 544 
hair_geo_curl, 321, 322, 325, 552 
hair_geo_datafile, 328, 329, 331, 
wee 
hair_geo_row, 312, 313, 547 
illuminated_volume, 381, 567 
instanced_object_file, 286, 538 
lambert, 151, 152, 167, 499 
lambert_steps, 118, 494 
letterbox, 441, 581 
median_filter, 445, 582 
mock_specular, 163,505 
normals_as_colors, 62, 477 
object_file, 284, 537 
one_color, 476 
op-mix_ccc, 212, 521 
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op_pow-_cs, 215, 521 
parameter_volume, 386, 569 
phong, 155, 500 
phong framebuffer, 424, 577 
point_light, 127, 495 
point_light_falloff, 147, 499 
point_light_shadow, 130, 167, 496 
radial_falloff, 388, 571 
rim_bright, 165, 507 
shadow_breakpoint, 172, 509 
shadow_breakpoint_scale, 175,510 
shadow_color, 169, 508 
shadow_continuous, 178, 511 
shadow_default, 168, 508 
shadowpass, 428, 579 
show_barycentric, 110, 491 
show_uv, 79, 482 
show_uv_steps, 81, 483 
sinusoid_soft_spotlight, 142, 498 
soft_spotlight, 139, 497 
specular_reflection, 184, 513 
specular_refraction, 203, 516 
specular_refraction_simple, 199, 
he 
spherical_density, 383, 568 
spotlight, 137, 496 
square, 274, 535 
store_diffuse_photon, 223, 523 
streak, 402, 574 
summed_noise_color, 91, 486 
summed_noise_scalar, 257, 530 
texture_uv, 85, 484 
texture_uv_simple, 84, 484 
threshold_volume, 373, 564 
transmit_specular_photon, 234, 
525 
transparent, 70, 481 
transparent_modularized, 74, 481 
transparent_shadow, 179, 511 
triangles, 281, 536 
vertex_color, 87, 485 
voxel_density, 391-393, 572 
ward, 162, 504 
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breakpoint concept, 172 
default behavior, 168 

included in material shader, 179 
mode, 379 

pass, 427 

receiving, 131 

segments, 378 

shader, 167 

soft, 143 
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sort order, 167 
Shirley, Peter, 5 
source code listings, 58 
Sparrow, E.M., 156 
spectral color shift, 158 
specular 
exponent, 154 
meaning in shaders, 183 
reflection, 183 
reflection models, 154 
refraction, 199 
state 
commonly used fields, 57 
conceptual categories, 57 
fields in miState 
state->bary, 60, 111, 292 
state->bary [1], 292, 315 
state->camera, 57 
state->camera->x_resolution, 
406 
state->camera->y_resolution, 
406 
state->child, 60 
state->derivs [0], 316 
state->dir, 60, 61, 133, 136, 155, 340, 358, 
362, 370, 400, 402, 407, 416, 418 
state->dist, 60, 146, 147, 358, 359, 366, 
370, 374 
state->dot_nd, 58-61, 114, 164 
state->environment, 60 
state->face, 60 
state->instance, 60 
state->inv_normal, 60 
state->ior, 60, 202 
state->ior_in, 60, 202 
state->label, 60 
state->light_instance, 60, 135 
state->material, 60 
state->normal, 60, 61, 155, 248, 260, 261, 
263, 265, 266, 319 
state->normal .x, 262 
state->normal.y, 262 
state->normal_geom, 60 
state->options, 427 
state->org, 60, 358, 362, 370, 400-403, 
407, 412, 416, 418 
state->parent, 60, 199 
state->parent->org, 135 
State->point, 60, 63, 133, 167, 250, 365, 
366, 380, 383, 384 
state->point), 250 
state->point.x, 250 
state->pri, 60, 383 
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state->pri_idx, 60 
state->raster_x, 406, 411 
state->raster_y, 406, 411 
state->reflection_level, 60, 
194 
state->refraction_level, 60 
state->refraction_volume, 60, 
i71 
state->scanline, 60 
state->shadow_tol, 60 
state->tex_list, 80, 308, 334 
state->tex_list.x, 80 
state->tex_list.y, 80 
state->tex_list [0], 79, 84, 86, 87, 250, 
251, 268 
state->tex_list [0] .x, 334 
state->time, 60 
state->type, 60, 179, 180, 201 
state->volume, 60 
hierarchy, 199 
intersection category, 59 
ray category, 60 
string parameter, 102, 281 
struct assignment, 70 
struct .mi type, 97 
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tag, 53, 102, 134 
tessellation, 106 

triangle size control, 106 
text editor, 13 
texture, 77 

coordinate system, 78, 82 

function, 77 

map, 82 

mapping, 40, 77 

projection, 86 

shader, 83 

space, 79 
toon shading, 112 
Torrance, K.E., 156, 158 
trace depth, 71, 184 
transformation matrix, 14 
transmissive ray, 201 
transparency, 69, 74 
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unit density, 361 
unit square, 12 
utility functions 
miaux_add_blinn_specular_component, 157, 
592 
miaux_add_color, 593 


miaux_add_cook_torrance_specular_component, 
158, 592 
miaux_add_diffuse_component, 149, 
S71 
miaux_add_diffuse_hair_component, 317, 
599 
miaux_add_light_color, 427, 606 
miaux_add_mock_specular_component, 162, 
594 
miaux_add_multiplied_colors, 596 
miaux_add_phong_specular_component, 154, 


592 
miaux_add_random_triangle, 279, 

597 
miaux_add_scaled_color, 110, 150, 

591 
miaux_add_specular_hair_component, 31/7, 

599 
miaux_add_transparent_color, 380, 

604 
miaux_add_transparent_hair_component, 

317, 599 


miaux_add_vertex, 279, 597 
miaux_add_ward_specular_component, 161, 
592 
miaux_adjust_bbox, 293, 598 
miaux_all_channels_equal, 73, 590 
miaux_alpha_blend, 607 
miaux_alpha_blend_colors, 380, 604 
miaux_altitude, 340, 602 
miaux_append_hair_data, 306, 598 
miaux_append_hair_vertex, 301, 598 
miaux_blend, 66, 589 
miaux_blend_channels, 73, 589 
miaux_blend_colors, 67, 589 
miaux_blend_transparency, 333, 
601 
miaux_brighten_rim, 164, 594 
miaux_clamp, 599 
miaux_clamp_color, 600 
miaux_color_channel_average, 596 
miaux_color_compare, 444, 607 
miaux_color_fit, 333, 602 
miaux_copy_color, 599 
miaux_copy_frame_buffer, 446 
miaux_current_light_tag, 135,591 
miaux_define_hair_object, 295, 598 
miaux_density_falloff, 375, 604 
miaux_describe_bbox, 293, 598 
miaux_distance, 605 
miaux_divide_color, 606 
miaux_divide_colors, 606 
miaux_fit, 66, 141, 589 
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miaux_fit_clamp, 593 
miaux_fractional_occlusion_at_point, 

379, 604 
miaux_fractional_shader_occlusion_at_point, 

385, 605 
miaux_from_camera_space, 416, 606 
miaux_hair_data_file_bounding_box, 328, 

601 
miaux_hair_spiral, 324, 600 
miaux_init_bbox, 293, 598 
miaux_interpolated_color_lookup, 351, 

603 
miaux_interpolated_lookup, 342, 

602 
miaux_invert_channels, 74, 590 
miaux_light_array, 151,591 
miaux_light_exponent, 146 
miaux_light_spread, 135,591 
miaux_load_fontimage, 448, 608 
miaux_march_point, 362, 603 
miaux_max, 599 
miaux_multiply_color, 596 
miaux_multiply_colors, 593 
miaux_object_from_file, 284, 597 
miaux_offset_spread_from_light, 136, 

591 
miaux_opacity_set_channels, 599 
miaux_parent_exists, 201,595 
miaux_perpendicular_point, 323, 

600 
miaux_piecewise_color_sinusoid, 351, 

603 
miaux_piecewise_sinusoid, 342, 

602 
miaux_pixel_neighborhood, 444, 

607 
miaux_point_along_vector, 362, 603 
miaux_point_between, 323, 600 
miaux_point_inside, 392, 605 
miaux_quantize, 113,591 
miaux_random_point_in_unit_sphere, 278, 

597 
miaux_random_point_on_sphere, 322, 

600 
miaux_random_range, 278, 597 
miaux_ray_is_entering, 201, 595 
miaux_ray_is_entering material, 199, 

595 
miaux_ray_is_transmissive, 201, 

595 
miaux_read_hair_data_file, 329, 

601 
miaux_read_volume_block, 390, 605 
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miaux_release_fontimage, 449, 607 
miaux_release_user_memory, 349, 

602 
miaux_sample_point_within_radius, 417, 

606 
miaux_scale_channels, 593 
miaux_scale_color, 592 
miaux_scale_vector, 590 
miaux_set_channels, 150, 591 
miaux_set_integer_if_not_default, 228, 

596 
miaux_set_scalar_if_not_default, 228, 

596 
miaux_set_state_refraction_indices, 203, 

596 
miaux_set_vector, 590 
miaux_shaders_equal, 201,595 
miaux_shadow_breakpoint, 172, 594 
miaux_shadow_breakpoint_scale, 174, 

594 
miaux_shadow_continuous, 176, 594 
miaux_sinusoid, 249, 260, 596 
miaux_sinusoid_fit, 141, 592 
miaux_sinusoid_fit_clamp, 594 
miaux_square_to_circle, 416, 606 
miaux_state_incoming_ior, 202, 595 
miaux_state_outgoing ior, 202, 595 
miaux_summed_noise, 90, 590 
miaux_tag_to_string, 102,590 
miaux_text_image, 450, 607 
miaux_threshold_density, 371, 604 
miaux_to_camera_space, 416, 606 
miaux_total_light_at_point, 379, 

604 
miaux_user_memory_pointer, 347, 

602 
miaux_world_space_march_point, 362, 

603 
miaux_z_plane_intersect, 417, 606 

uv coordinates, 78 
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viewing plane, 399 
Vince, John, 5 
visual hierarchy, 3 
visual index, 54 
voxels, 389 

data file format, 390 
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Ward, Greg, 160 
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wide-angle lens, 408 
Winston, Patrick Henry, 5 
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mental images GmbH 
EVALUATION SOFTWARE USER AGREEMENT 
AND SOFTWARE LICENSE TERMS 


Use of the Software provided to you on the enclosed media is subject to the terms of this 
Agreement. You should not open the software license envelope until you have read the 
Agreement. By opening the envelope, you signify that you have read this Agreement and 
accept its terms. If you do not agree to the terms of this Agreement, then mental images is 
unwilling to license the Software to you. 


This mental images Evaluation Software User Agreement And Software License Terms (the 
“Agreement”) is a legal agreement between you and mental images GmbH, a German limited 
liability company (“mental images”) for mental ray. In this Agreement, the term “Software” 
means mental ray, including computer software and associated media and printed materials, and 
may include “online” or electronic documentation. The term “Software” shall include all future 
evaluation versions of the Software and all information concerning such future evaluation 
versions. The term “You” or “you” means the company, entity or individual who is evaluating 
the Software. The term “Use” means storing, loading, installing, executing or displaying the 
Software. 


License Grant — Evaluation Use of Software Only. mental images grants you the right to 
download and use the evaluation version of the Software solely for the purpose of evaluating the 
Software for potential purchase or for your personal educational purposes, subject to the terms 
and conditions of this Agreement. You acknowledge that the Software may contain software 
procedures or other mechanisms (“License Enforcement Mechanisms”) that enforce use 
restrictions and that may disable functionality of the Software and prevent access to data using 
the Software. 


Obligations. Unless otherwise specifically agreed by mental images in writing, you: (a) shall 
not copy, distribute, transfer, loan or otherwise provide the Software to any third party outside 
your own organization; (b) shall not reverse compile, reverse engineer or disassemble the 
Software (except solely in the circumstances where you are required to be permitted to do so 
under applicable local law); (c) may not modify, disable, attempt to circumvent or otherwise 
interfere with any License Enforcement Mechanisms, and acknowledge that any attempt to do 
so may be a violation of applicable law; and (d) shall display, and shall not alter or remove, 
mental images’ copyright and other proprietary notices. 


Ownership. You acknowledge and agree that the Software is owned and copyrighted by mental 
images or its third party suppliers. Your license confers no title or ownership in the Software 
and is not a sale of any rights in the Software. All ownership rights remain in mental images or 
its third party suppliers, as the case may be. 


NO WARRANTY AND NO LIABILITY. Due to the purpose that the Software is being 
supplied to you (evaluation for purchase or for your personal educational purposes only), 
mental images makes no warranties whatsoever as to the operational performance of the 
Software. mental images will not provide any support or bug-fixes for the Software. TO THE 
MAXIMUM EXTENT PERMITTED BY LAW, MENTAL IMAGES DISCLAIMS ALL 
WARRANTIES, EXPRESS OR IMPLIED. IN PARTICULAR, THE SOFTWARE IS 
PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, INCLUDING 
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WITHOUT LIMITATION THE WARRANTIES OF MERCHANTABILITY, FITNESS 
FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. The entire risk as to the 
quality and performance of the Software is borne by you. Should the Software prove defective, 
you and not mental images assume the entire cost of any service and repair. This disclaimer of 
warranty constitutes an essential part of this Agreement. SOME JURISDICTIONS DO NOT 
ALLOW EXCLUSIONS OF AN IMPLIED WARRANTY, SO THIS DISCLAIMER MAY 
NOT APPLY TO YOU AND YOU MAY HAVE OTHER LEGAL RIGHTS THAT VARY 
BY JURISDICTION. 


Because software is inherently complex and may not be completely free of errors, you are 
advised to verify and back up your work. Additionally, mental images does not guarantee 
compatibility between the Software and any non-evaluation or future versions of the 
Software. 


LIMITATIONS ON LIABILITY. TO THE MAXIMUM EXTENT PERMITTED BY LAW, 
UNDER NO CIRCUMSTANCES AND UNDER NO LEGAL THEORY, TORT, 
CONTRACT, OR OTHERWISE, SHALL MENTAL IMAGES BE LIABLE TO YOU OR 
ANY OTHER PERSON FOR ANY MONEY DAMAGES, WHETHER DIRECT, 
INDIRECT, SPECIAL, INCIDENTAL, COVER, RELIANCE OR CONSEQUENTIAL 
DAMAGES, EVEN IF MENTAL IMAGES SHALL HAVE BEEN INFORMED OF THE 
POSSIBILITY OF SUCH DAMAGES, OR FOR ANY CLAIM BY ANY OTHER PARTY. 
IN THE EVENT THAT NOTWITHSTANDING THE FOREGOING, MENTAL 
IMAGES IS FOUND LIABLE TO YOU FOR DAMAGES FROM ANY CAUSE 
WHATSOEVER, AND REGARDLESS OF THE FORM OF THE ACTION (WHETHER 
IN CONTRACT, TORT (INCLUDING NEGLIGENCE), PRODUCT LIABILITY OR 
OTHERWISE), MENTAL IMAGES’ LIABILITY TO YOU WILL BE LIMITED TO THE 
GREATER OF US$25 OR THE AMOUNT YOU PAID FOR THE SOFTWARE. SOME 
JURISDICTIONS DO NOT ALLOW THE EXCLUSION OR LIMITATION OF 
INCIDENTAL OR CONSEQUENTIAL DAMAGES, SO THIS LIMITATION AND 
EXCLUSION MAY NOT APPLY TO YOU. 


Export Controls. None of the Software or underlying information or technology may be 
downloaded or otherwise exported or reexported in violation of United States export control 
law, including to anyone on the U.S. Treasury Department’s list of Specially Designated 
Nationals or the U.S. Commerce Department’s Table of Denial Orders. By downloading or 
using the Software, you are agreeing to the foregoing and you are representing and warranting 
that you are not located in, under the control of, or a national or resident of any country to 
which such export is so prohibited or on any such list. In addition, you are responsible for 
complying with any local laws in your jurisdiction which may impact your right to import, 
export or use the Software, and you represent that you have complied with any regulations or 
registration procedures required by applicable law to make this license enforceable. 


U.S. Government End Users. The Software is a “commercial item,” as that term is defined in 
48 C.ER. 12.101 (Oct. 1995), consisting of “commercial computer software” and “commercial 
computer software documentation,” as such terms are used in 48 C.ER. 12.212 (Sept. 1995). 
Consistent with 48 C.ER. 12.212 and 48 C.ER. 227.7202-1 through 227.7202-4 (June 1995), all 
U.S. Government End Users acquire the Software with only those rights set forth herein 


Term. Your license under this Agreement is effective permanently unless terminated. Either 
you or mental images may terminate this license at any time. Upon any such termination or 
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expiration, you must discontinue all use of the Software, and immediately destroy the Software 
together with all copies. The provisions of this Agreement (other than your license to use the 
Software) shall survive the termination of the license, or the termination or expiration of this 
Agreement. 


Controlling Law and Severability. This Agreement constitutes the entire agreement between 
you and mental images with reference to this transaction. This Agreement will be governed by 
the laws of the Commonwealth of Massachusetts, USA, except for that body dealing with 
conflicts of law. The application to this Agreement of the United Nations Convention on 
Contracts for the International Sale of Goods is hereby expressly excluded. In the event of any 
dispute involving this Agreement, mental images and you each consent to exclusive jurisdiction 
and venue in either the state or federal courts in the Commonwealth of Massachusetts and 
agrees that the prevailing party shall be entitled to its reasonable attorney fees and costs. In the 
event any provision of this Agreement shall be deemed unenforceable, void or invalid, such 
provision shall be modified so as to make it valid and enforceable, and as so modified the entire 
Agreement shall remain in full force and effect. No decision, action or inaction by mental 
images shall be construed to be a waiver of any rights or remedies available to it. 
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Rendering with mental ray® 


Third, completely revised edition. 

2005. XV, 626 pages. 195 figures (48 colored). With CD-ROM. 
Softcover EUR 69,- 

(Recommended retail price) 

Net-price subject to local VAT. $) SpringerWien NewYork 
ISBN 978-3-211-22875-6 

mental ray Handbooks, Volume 1 al 


Written by the mental ray software project leader, this book gives a general intro- 
duction into rendering with mental ray, as well as step-by-step recipes for creat- 
ing advanced effects and tips and tricks for professional users. A comprehensive 
definition of mental ray’s scene description language and the standard shader 
libraries are included as the basis for all examples. 

The third, completely revised edition covers the latest version of the new gene- 
ration of mental ray, version 3.4. A CD with a fully programmable demo version 
of the software, together with example scene data and shaders that are descri- 
bed in the book, is enclosed. 


From the contents: 


Introduction * Overview * Scene Construction * Cameras * Surface Shading * Light 
and Shadow * Volume Rendering * Caustics and Global Illumination * Motion Blur 
* Hardware Rendering * Contours * Shaders and Phenomena * Postprocessing 
and Image Output * Geometric Objects * Instancing and Grouping « Inheritance 
* Incremental Changes and Animations * Using and Creating Shader Libraries 
Parallelism * The Options Block * The Architecture of mental ray 3.x * Quality and 
Performance Tuning * Troubleshooting * Color Plates * Command Line Options ° 
The Sphere and Utah Teapot Models * Base Shaders * Physics Shaders * Contour Sha- 
ders * Glossary/Bibliography/Index 


D) SpringerWien NewYork 


P.O. Box 89, Sachsenplatz 4-6, 1201 Vienna, Austria, Fax +43.1.330 24 26, books@springer.at, springer.at 

HaberstraBe 7,69126 Heidelberg, Germany, Fax +49.6221.345-4229, SDC-bookorder@springer-sbm.com, springeronline.com 
P.O. Box 2485, Secaucus, NJ 07096-2485, USA, Fax +1.201.348-4505, orders@springer-ny.com, springeronline.com 

Prices are subject to change without notice. All errors and omissions excepted. 
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Programming mental ray® 


Third, completely revised edition. 
2005. XVI, 825 pages. With CD-ROM. 
Softcover EUR 129,- 
(Recommended retail price) 
Net-price subject to local VAT. 2. 
ISBN 978-3-211-24484-0 


mental ray Handbooks, Volume 2 


@) SpringerWien NewYork 


This book is the definitive reference manual for mental ray version 3.4. It starts 
with a brief overview of the features of mental ray and continues with the spe- 
cification of the mental ray scene description language, the mental ray shader 
interface, and the integration interface for third-party applications. All material 
is presented in reference form, organized by grammar elements and C function 
call, rather than by feature set. The book is intended for translator writers, shader 
writers, and integrators who are familiar with the C and C++ programming lan- 
guages. This third, completely revised edition was extended to cover the new 
generation of mental ray, version 3.4, throughout the book, and also includes 
the mental ray integration manual. The enclosed CD contains a demo version of 
the mental ray stand alone and the mental ray library, as well as example shaders 
with source code and demo scenes, for a variety of computer platforms. 


Description of the contents: 

Chapter 1 gives a brief overview of the functionality of mental ray. Chapter 2 
describes the scene language in detail. This chapter is organized by language 
unit. Chapter 3 explains how custom shaders and Phenomena™ are written and 
documents the shader call interface. Chapter 4 describes the extended geome- 
try shader interface. Chapter 5 describes the integration interface of the library 
version of mental ray. This chapter is useful only for application developers, and 
not part of the standard mental ray manual. Chapter 6 contains porting guide- 
lines for users and shader writers upgrading from mental ray 3.x to mental ray 
3.4. Appendix A describes the command-line interface of mental ray. Appendix B 
contains the source code of mental ray’s scene language parser. 


G) SpringerWien NewYork 


P.O. Box 89, Sachsenplatz 4-6, 1201 Vienna, Austria, Fax +43.1.330 24 26, books@springer.at, springer.at 

HaberstraBe 7, 69126 Heidelberg, Germany, Fax +49.6221.345-4229, SDC-bookorder@springer-sbm.com, springeronline.com 
P.O. Box 2485, Secaucus, NJ 07096-2485, USA, Fax +1.201.348-4505, orders@springer-ny.com, springeronline.com 

Prices are subject to change without notice. All errors and omissions excepted. 


ee 


fe 


= 
- 
sir & =“ S2 
‘ 
) 
4 ; ; +5 
= a 
; 4 >= 
; ] 
=> 


, ate 


te op '" a 


- 


aa) 


Sie: 


ic rm WHATS ss 


“Writing mental ray® Shaders: a Perceptual Introduction” 
describes the creation and use of the software modules 
known as shaders in the mental ray rendering system. 

In mental ray, shaders can customize the entire rendering 
pipeline, from the simulated camera lens to object 
geometry and appearance and to the output of the final 
image. Intended both for experienced programmers 
new to mental ray and for artists learning how to program, 
this book presents the various shader types in an 
intuitive order based on a model of visual perception. 
With over one hundred example shaders and their 
associated scene files and explanatory diagrams, both 
beginning and advanced shader programmers will find 
the book’s catalog of techniques useful in customizing 
mental ray. Serving as a tutorial guide to the first two 
volumes in the “mental ray Handbooks” series, the 
present book provides further information on any topic 
it discusses by detailed references to those previous books. 
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